Coding Guidelines |
| Like other projects, we also have some guidelines to keep to the code. In general, three rough rules are: - Most importantly, we never say "It's in POSIX; we'll happily ignore your needs should your system not conform to it." We live in the real world. - However, we often say "Let's stay away from that construct, it's not even in POSIX". - In spite of the above two rules, we sometimes say "Although this is not in POSIX, it (is so convenient | makes the code much more readable | has other good characteristics) and practically all the platforms we care about support it, so let's use it". Again, we live in the real world, and it is sometimes a judgement call, the decision based more on real world constraints people face than what the paper standard says. As for more concrete guidelines, just imitate the existing code (this is a good guideline, no matter which project you are contributing to). But if you must have a list of rules, here they are. For shell scripts specifically (not exhaustive): - We prefer $( ... ) for command substitution; unlike ``, it properly nests. It should have been the way Bourne spelled it from day one, but unfortunately isn't. - We use ${parameter-word} and its [-=?+] siblings, and their colon'ed "unset or null" form. - We use ${parameter#word} and its [#%] siblings, and their doubled "longest matching" form. - We use Arithmetic Expansion $(( ... )). - No "Substring Expansion" ${parameter:offset:length}. - No shell arrays. - No strlen ${#parameter}. - No regexp ${parameter/pattern/string}. - We do not use Process Substitution <(list) or >(list). - We prefer "test" over "[ ... ]". - We do not write the noiseword "function" in front of shell functions. - As to use of grep, stick to a subset of BRE (namely, no \{m,n\}, [::], [==], nor [..]) for portability. - We do not use \{m,n\}; - We do not use -E; - We do not use ? nor + (which are \{0,1\} and \{1,\} respectively in BRE) but that goes without saying as these are ERE elements not BRE (note that \? and \+ are not even part of BRE -- making them accessible from BRE is a GNU extension). For C programs (and PHP where applicable): - We use tabs to indent, and interpret tabs as taking up to 8 spaces. - We try to keep to at most 80 characters per line. - When declaring pointers, the star sides with the variable name, i.e. "char *string", not "char* string" or "char * string". This makes it easier to understand code like "char *string, c;". - We avoid using braces unnecessarily. I.e. if (bla) { x = 1; } is frowned upon. A gray area is when the statement extends over a few lines, and/or you have a lengthy comment atop of it. Also, like in the Linux kernel, if there is a long list of "else if" statements, it can make sense to add braces to single line blocks. - We try to avoid assignments inside if(). - Try to make your code understandable. You may put comments in, but comments invariably tend to stale out when the code they were describing changes. Often splitting a function into two makes the intention of the code much clearer. - Double negation is often harder to understand than no negation at all. - Some clever tricks, like using the !! operator with arithmetic constructs, can be extremely confusing to others. Avoid them, unless there is a compelling reason to use them. - Use the API if one is provided. Not doing so means there's more code to maintain. - When you come up with an API, document it. - Avoid introducing a new dependency. This means you usually should stay away from scripting languages not already used in the project (unless your command is clearly separate from it). |