18 ms·
Google's Shell Style Guide
- thejosh 13y agoRest of languages here: https://code.google.com/p/google-styleguide/source/browse/trunk https://code.google.com/p/google-styleguide/source/browse/tr...
- hacker789 13y agohttp://google-styleguide.googlecode.com/svn/trunk/shell.xml?showone=File_Extensions#File_Extensions http://google-styleguide.googlecode.com/svn/trunk/shell.xml?... > It is not necessary to know what language a program is written in when executing it and shell doesn't require an extension so we prefer not to use one for executables. I disagree with their recommendation against using file extensions for executables, and I'd love to have my mind changed about this. Using an extension gives you automatic syntax highlighting. It also lets you quickly glean the type of a file when exploring a directory for the first time, which is more helpful than simply knowing whether the file can be executed. Why does a lack of necessity override those two benefits?
- flebron 13y agoYour benefits are so to people who are going to be editing these files. They are not benefits to people who are going to be using these files (i.e. running the script). Most people are not going to be editing the script, they are going to be using it. Thus, it makes sense to cater to them, and to not have them have to know things they don't care about, like what language the tool they are using was programmed in.
- jfb 13y agoAny serious editor will read the #! line for syntax highlighting, which has the benefit of being much more likely to be correct than the user visible and modifiable file name.
- raverbashing 13y agoExcept when it doesn't have that line because it's a C/C+header file. And then the editor doesn't know what to do with that header file without extension. Yes, if you see some Google C++ code they do that Really, horrible practice.
- kondro 13y agoWhat are you doing making C header files executable?
- raverbashing 13y agoWhere did I say I was making it executable?
- kondro 13y agoThey were only advocating no extension for executable shell files, not all files.
- raverbashing 13y agoYes, I remembered seeing a C++ google product without the .h extension in header files (or other similar extensions) But apparently they stopped this nonsense
- ithkuil 13y agoIt's not google, it's C++ convention. http://stackoverflow.com/questions/301586/what-is-the-difference-between-using-includefilename-and-includefilename-h http://stackoverflow.com/questions/301586/what-is-the-differ... Btw, many editors understand // -- C++ -- Nevertheless Google's c++ style guide (https://code.google.com/p/google-styleguide/source/browse/trunk/cppguide.xml https://code.google.com/p/google-styleguide/source/browse/tr...) in fact says that headers should have the .h suffix.
- nsmartt 13y agoThe extension is unnecessary for syntax highlighting. Shebang lines are supposed to be used for detecting the file type. As for knowing the file type at a glance, I'm not sure how often I need this. I'm normally looking for the file by name anyway. If I needed to determine the file-type, I'd write a script to parse the shebang lines of executable files in the current directory and generate a list of the files with their hypothetical extensions (based on a hash/dictionary/whatever). I don't need that very often, so, for me, the trade is worth it.
- xwowsersx 13y agoI'm new to shell scripting and I'm clearly missing something basic. Why can't you use file extensions? This is saying not to use .sh for bash scripts and .rb for ruby scripts, etc?
- packetslave 13y agoOne reason: let's say you write tool 'foo.sh' in Bash. It does what you want and you move on to other things. It's suddenly a year from now, and your foo.sh tool needs some new features, or is too slow to do the job any more because your requirements have changed. You decide it's grown too much for Bash and want to move to Python for maintainability, or Go for performance, or C++ to link with some library you need to use. Now you have to tell your team (and any other teams that have found your tool useful): "We only want to maintain one version, so don't use 'foo.sh' any more. You have to use 'foo.py' (or 'foo.exe' or whatever). Oh, and have fun changing all YOUR scripts and tools that reference 'foo.sh'!" That's one reason.
- MBlume 13y agoNow I'm wondering how many shops have some legacy script with a 'foo.sh' filename and a #!/usr/bin/python shebang
- tlarkworthy 13y agoyeah, that's a good reason. I am convinced.
- oblio 13y agoNot really, I'd rather do: https://news.ycombinator.com/item?id=6688782 https://news.ycombinator.com/item?id=6688782
- oblio 13y agoWell, you do have some sort of deployment process, right? (as in, you're not attaching your scripts to emails) Just change it to zip foo.sh + foo.py. Then: cat foo.sh #!/bin/bash -e ./foo.py cat foo.py # Everything else has moved here. Much better.
- deleted 13y ago[deleted]
- dredmorbius 13y ago(This point is also made lower down). When you run a program, your concern should be what it is called. Not how it is written. A language-specific filename extension puts an implementation detail in userspace. If you run a binary executable, you shouldn't care whether it's written in C, C++, Fortran, or any other language (though source files, being used only by developers and compilers, generally do have extensions). Worse: if you decide for whatever reason to change the implementation language, you're either forced to track down and change all references to the program name, or to retain the (now incorrect) filename extension for backwards compatibility. And, as noted, magic(5) or the shebang line should correctly identify the file type and language for syntax highlighting -- if not, your editor is broken. Replace it with a shell script, "editor.sh". file(1) will tell you the types of files in a directory with far greater accuracy than filename extensions can.
- hacker789 13y agoThat makes sense. I think of shell scripts as "things programmers execute", but that's obviously not always the case.
- dredmorbius 13y agoThey're very often things other programs execute. Cron jobs, other scripts, production jobs, etc. So having to hunt down and rename everything ... is a PITA.
- txutxu 13y agoWe don't use to run grep.c, or ansible.py, or git.c, or gunzip.sh, etc... explore a directory? file -i directory/* I follow the same convention than Google, just that I use .bash for libraries instead of .sh (as they state the interpreter should be bash, I think they should apply my naming instead of .sh)
- js2 13y agoRe: long pipelines, the guide suggests: # Long commands command1 \ | command2 \ | command3 \ | command4 However, by ending each line with the pipe the continuation is implicit and the backslashes may be omitted: # Long commands command1 | command2 | command3 | command4
- deleted 13y ago[deleted]
- dredmorbius 13y agoPipes, and logical operators (&&, ||) can continue lines in bash. I find it convenient, and generally clear, to break longer constructions using these operators with them.
- emmelaich 13y agoI usually use the trailing | but I can certainly see the sense in the leading pipe. It makes it clearer that the lines following are continuations; especially the last in the pipeline.
- sesqu 13y agoI consider the leading pipe clearer, and could be sold on it, but ending each line with an inconvenient slash character (non-US layout) makes me strongly favor the trailing version. The trailing version seems more natural with operators like comma, but less natural with operators like minus, and is far clearer with semicolonless languages. I suspect if I were to go through old code, I'd find both uses, but generally I prefer trailing. The exception to this is languages like Haskell, though indentation could serve the same purpose.
- andrewkreid 13y ago>> ...One example of this is Solaris SVR4 packages... I wonder what Google are using Solaris for, and if it's just legacy stuff.
- tmallen 13y agoGoogle is likely supporting Solaris for customers or for users of their open source software.
- arethuza 13y agoGoogle appear to use Oracle Hyperion Financial Management for consolidated reporting and planning (search their job pages - they usually have ads) - I would suspect that this runs on Oracle boxes running Solaris.
- zobzu 13y ago"Indent 2 spaces. No tabs." Well fuck it. Thats the only coding style that remotely makes sense to me: https://www.kernel.org/doc/Documentation/CodingStyle https://www.kernel.org/doc/Documentation/CodingStyle While I'm at it, half the justifications Google gives for the shell guide are inaccurate. Looks like a "overall people are used to this style so we're using it and we'll try to justify it without knowing why" This is a much better guide: http://devmanual.gentoo.org/tools-reference/bash/ http://devmanual.gentoo.org/tools-reference/bash/ Example: Gentoo's [[ ]] explanation actually makes sense.
- nsmartt 13y agoI've always been conflicted on this. It's simply untrue that more than 3 levels of indentation indicates bad code. For example, HTML, XML, and JSON often benefit from deeper levels of indentation. Tabs have the benefit of having a dynamic size, so I could simply adjust the tab width within my editor. Spaces also do not play as well with editors. Unfortunately, browsers offer no means to change the width of tabs, so it's impossible to properly display code using tabs. This is especially frustrating when reading the source of a page indented using tabs. It would be much easier to read with spaces, but not as easy to read as if I were able to set tab width.
- GuiA 13y agoHTML, XML, and JSON are document description formats. For most programming languages, more than 3 levels of indentation is a red flag.
- nsmartt 13y agoWhile it's true of some languages, it's certainly not true of all of them. I'm not sure most is accurate either. JSON is a subset of JavaScript, so it stands to reason that JavaScript could have as many indentation levels as JSON without a loss of clarity. It also stands to reason that any language with hashes, dictionaries, etc could feasibly exceed 3 indentation levels without it being a red flag, particularly if those hashes are in a method that is already indented more than one or two levels.
- frozenport 13y agoWhats wrong with tabs?
- laurent123456 13y agoOne possible reason is that if you copy a line with tabs from the terminal, you're actually going to end up with the tab converted to spaces in the clipboard. If you use spaces everywhere, you won't have this problem.
- sounds 13y agoCoding in the terminal does have its drawbacks. That can't be an argument for using spaces in code, right? Rather, the terminal should keep track of which parts of its display were generated by a tab character in case the user copies the output?
- jfb 13y agoNothing intrinsically, but there is value in consistency, and Google's decided on spaces. One of the rationales for these guides is to give the programmer a way to make a decision about questions where there is no single correct answer.
- 10098 13y agoWell, sometimes I need to align my lines in a certain way (e.g., if function arguments are on multiple lines, I want them to align with each other). It's often impossible to do with tabs, because they are fixed width, so I have to add spaces. But when other people view my code, and their tab width is different, it all goes to chaos. That's why I prefer spaces over tabs.
- philsnow 13y agotab to the indentation of the previous line, then pad with spaces def foo(): TTbar(asdf, zxcv, TTSSSSqwer, oiuy) no matter what anybody uses for tab stop size, the alignment won't get messed up.
- 13y ago
- rurounijones 13y ago"It should be possible for someone else to learn how to use your program or to use a function in your library by reading the comments (and self-help, if provided) without reading the code." I know a few "Use the source, Luke" people who will rage at that.
- jakejake 13y agoWhen I read that and also the section about using spaces instead of tabs I immediately thought - uh oh, here comes the nerd rage!
- nsmartt 13y agoThe best argument I've seen here is that methods should be black boxes. Comments should reveal the input, output, and side effects of a method. There are two compelling reasons for this: - I can add to my own code, even if it's years old, without re-reading every line every of every method I need - I can contribute to a code-base built by multiple people without reading every line they've written
- sounds 13y agoThat is a particularly useful approach in functional languages, where the function declaration itself is actually a fairly concrete guarantee of what the function will do. Shell scripts are almost the complete opposite end of the spectrum: Shell script functions are usually only created as a last resort. Global side effects (creating temporary files, changing global system state, global variables, etc.) are what shell scripts are all about. There are rare snippets of shell scripting that are different, using local variables and doing some sort of calculation, but that is the exception, not the rule. While ideally comments would be prolific, poetic, and perfect, some commenting is always better than none and most developers have bad habits of not commenting their code, so pushing them gently in the direction of more, not less, usually works.
- sillysaurus2 13y agoShell script functions are usually only created as a last resort. Hence why they'd prefer you write Python, not shell.
- bcoates 13y agoI'm surprised there isn't more commentary on when and how to use external but standard or common commands like grep, sed, awk, perl, join, find, tar, parallel, etc. It's one thing to use bash consistently everywhere but as a heavy multi-machine shell user I've been bitten by incompatible or missing external utilities more often than I care to admit. You might be surprised how many systems aren't using the GNU utilities, have them running in a weird mode or are using ancient versions of them. Maybe Google is religious about keeping all their environments identical?
- clarkm 13y agoAnd when you bring OS X into the picture, guaranteeing portability becomes a nightmare, especially when it comes to scripts that have anything to do with networking.
- dredmorbius 13y agoSome things I don't particularly care for (2 space indent? SRSLY?!!), but it warms the cockles of my heart to see an 80 character line limit. Yes, it matters.
- fhd2 13y agoYeah, Google has 80 column limits for almost every language (except for Java, it's pretty difficult there). So does Mozilla and all major open source projects I can think of (again, Java being the exception). It really does a lot for readability. I recently summed up my reasons for doing it in all of my projects: http://ubercode.de/blog/80-columns http://ubercode.de/blog/80-columns
- dredmorbius 13y agoThe argument-ender for me is: Look, when I'm at the DC, on console, with an 80 column screen, I cannot make my terminal any wider than 80 characters, and the site is down. This also applies for a lot of remote-access tools -- serial console as well as direct, so even if I'm not at the DC, once I'm on those interfaces, something's likely fucked up or headed that way.
- deleted 13y ago[deleted]
- barrkel 13y agoAn 80 character line limit almost mandates use of a 2 space indent, for most languages. Personally I prefer a line limit closer to 100, and 4 space indents in most languages. Some languages end up with a lot more indenting than others owing to structural literals and lambdas, and they benefit more from a smaller indent.
- dredmorbius 13y agoI manage 80 chars (with very few exceptions) and a 4-space indent. Copious use of bash functions helps.
- emmelaich 13y agoThe most important point: Shell should only be used for small utilities or simple wrapper scripts
- rat87 13y agoUnfortunately firefox 24(on windows) has problems with rendering the style of the xsl stylesheet and gives crap putput(Basically the full text content with no line breaks). It seems to work on firefox 21/linux though. Also ie8/windows and chrome 30/windows chromium 25/linux work.
- AYBABTME 13y agoThanks for `go fmt`.
- ushi 13y agoI had the exact same thought. The Go community is the only one (i know), where such discussions are rare. Write your code, run "go fmt", add, commit.
- eriksank 13y agoThese rules look like they came from the low-intelligence paper belt. We do not write rules like that. They must simply be part of the tool. Otherwise, they do not count. What they now did, was to create an opportunity for someone who knows that he is incompetent, to invent a new job for himself, that is, "checking up" with his more competent colleagues, who contrary to him are productive in writing code, on this style guide. Rule number one: Anybody who wants to "enforce" this kind of rules must demonstrate that he is capable of writing a parser that can apply them. It is simply bad practice to create that kind of opportunities. It is bad practice to create that kind of jobs. Therefore, this kind of documents must be rejected.
- CraigJPerry 13y agoI think that's a bit harsh. Of course we write style guides and while I like the idea that it's part of the tool, that's rarely the case. I don't follow the objection about a colleague helping ensure consistency across a team. I'm really not sure why competence comes into that equation either. Agree with the idea any style guide should be automated. Several CI servers I know of can incorporate style checkers and their reports into their workflow so this can be made really hands off, even to the point of automatically failing code review stage before its been lumped in the review queue. Don't agree at all with the idea this type of doc should be rejected. In fact it's completely wrong to jump into automation without having "found which way is up" manually first time around.
- Shorel 13y agoActually, they came from very smart, well intentioned people, who thought everyone would program Lisp in this century. And of course never saw C (and all its related family of languages) coming and ruling for decades. All these rules make sense for Lisp, and no sense at all for C. And they did wrote the parser that applies those rules, in Emacs you never indent Lisp code, you press a key and the current s-expr automagically indents better than you could ever dream of doing it.
- MichaelMoser123 13y agoI almost always use set -e with my bash scripts; this way you will always notice if an invoked command failed or not; your script will not report that everything is OK if part of the process actually failed. https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html#The-Set-Builtin https://www.gnu.org/software/bash/manual/html_node/The-Set-B... Also: set -x is the best debugger in the world; really.
- MichaelMoser123 13y agoAlso useful trick is to have exit traps, doing stuff on exit. http://linux.die.net/Bash-Beginners-Guide/sect_12_02.html http://linux.die.net/Bash-Beginners-Guide/sect_12_02.html
- penguindev 13y agoYeah, surprised that got no mention. I thought the ./* wildcarding for safety was really cool. they also could have covered find -print0 | xargs -0 for safety. I'm glad they talked about "$@" being usually always the right thing to do. That's been a hard won learning experience for me in the past...
- pirateking 13y agoStyle guides are the worst to me. Taking some of the small joys left in programming away, while making you feel like a cog at the same time. Especially since many are outdated or just plain wrong, and very difficult to change once established. Tools that take the AST and output standardized code for peer review and documentation sounds a little better. It would not deal well with the only human problem really worth having a style guide for - naming things. But at least humans aren't forced to jump through hoops. And the naming thing possibly can be settled with an interface that asks something like - "what do you want everyone to call the 'BitWarper' symbol?", for all named symbols. But well written software is no place to express individuality - we just want it to work and not make our eyes bleed when we have to fix it! Even better then, just have machines generate and test all the code based on systems of higher order rules and style guides in situations where factory manufactured code is necessary. The outputs should be reasonable if the requirements are well specified (NASA style). Humans can come in after and do the real fun work in optimizing and finding clever hacks (if environment is not mission critical and such liberty can be safely taken). Having humans program character by character, with their bare hands, while also suppressing creativity, is unnecessary in this Post-Industrial Age.
- jebblue 13y agoi'm going to have to bookmark this site, I'm no Bash expert but with some Bash and Java and a bit of Python here and there, sometimes I feel like I could save the world.
- txutxu 13y agoI've seen many scripts wrapping steps inside a main() function and calling it just after declaration. If the justification is to localize variables which should be global, and still will look like "global" to the rest of the program, it's ok. But this is mainly used without sense, by personal tastes, and usually only makes sense to the author and does not have any real benefice. I prefer the concept "consistency is to not read unuseful steps", instead of "add unuseful steps for consistency". That's how I think when I read code.
- txutxu 13y agoOther one from the summaries: I don't see how $((${X} + ${Y})) ... is more recommendable than ... $(( X + Y )) for example. But well, guide styles are a good thing, and this one can help to many people "not used" to deal with shell scripts to follow some basics. Edit: and help to people used to it, on working in a team.
- rainhacker 13y agoUnder the section 'When to use Shell', why does the style guide say 'If performance matters, use something other than shell' ? I was under impression that since shell script is low level it should have superior performance.