@@ -18,6 +18,14 @@ code. For Git in general, three rough rules are:
1818 judgement call, the decision based more on real world
1919 constraints people face than what the paper standard says.
2020
21+ - Fixing style violations while working on a real change as a
22+ preparatory clean-up step is good, but otherwise avoid useless code
23+ churn for the sake of conforming to the style.
24+
25+ "Once it _is_ in the tree, it's not really worth the patch noise to
26+ go and fix it up."
27+ Cf. http://article.gmane.org/gmane.linux.kernel/943020
28+
2129Make your code readable and sensible, and don't try to be clever.
2230
2331As for more concrete guidelines, just imitate the existing code
@@ -34,7 +42,17 @@ For shell scripts specifically (not exhaustive):
3442
3543 - We use tabs for indentation.
3644
37- - Case arms are indented at the same depth as case and esac lines.
45+ - Case arms are indented at the same depth as case and esac lines,
46+ like this:
47+
48+ case "$variable" in
49+ pattern1)
50+ do this
51+ ;;
52+ pattern2)
53+ do that
54+ ;;
55+ esac
3856
3957 - Redirection operators should be written with space before, but no
4058 space after them. In other words, write 'echo test >"$file"'
@@ -43,6 +61,14 @@ For shell scripts specifically (not exhaustive):
4361 redirection target in a variable (as shown above), our code does so
4462 because some versions of bash issue a warning without the quotes.
4563
64+ (incorrect)
65+ cat hello > world < universe
66+ echo hello >$world
67+
68+ (correct)
69+ cat hello >world <universe
70+ echo hello >"$world"
71+
4672 - We prefer $( ... ) for command substitution; unlike ``, it
4773 properly nests. It should have been the way Bourne spelled
4874 it from day one, but unfortunately isn't.
@@ -81,14 +107,33 @@ For shell scripts specifically (not exhaustive):
81107 "then" should be on the next line for if statements, and "do"
82108 should be on the next line for "while" and "for".
83109
110+ (incorrect)
111+ if test -f hello; then
112+ do this
113+ fi
114+
115+ (correct)
116+ if test -f hello
117+ then
118+ do this
119+ fi
120+
84121 - We prefer "test" over "[ ... ]".
85122
86123 - We do not write the noiseword "function" in front of shell
87124 functions.
88125
89- - We prefer a space between the function name and the parentheses. The
90- opening "{" should also be on the same line.
91- E.g.: my_function () {
126+ - We prefer a space between the function name and the parentheses,
127+ and no space inside the parentheses. The opening "{" should also
128+ be on the same line.
129+
130+ (incorrect)
131+ my_function(){
132+ ...
133+
134+ (correct)
135+ my_function () {
136+ ...
92137
93138 - As to use of grep, stick to a subset of BRE (namely, no \{m,n\},
94139 [::], [==], or [..]) for portability.
@@ -106,6 +151,19 @@ For shell scripts specifically (not exhaustive):
106151 interface translatable. See "Marking strings for translation" in
107152 po/README.
108153
154+ - We do not write our "test" command with "-a" and "-o" and use "&&"
155+ or "||" to concatenate multiple "test" commands instead, because
156+ the use of "-a/-o" is often error-prone. E.g.
157+
158+ test -n "$x" -a "$a" = "$b"
159+
160+ is buggy and breaks when $x is "=", but
161+
162+ test -n "$x" && test "$a" = "$b"
163+
164+ does not have such a problem.
165+
166+
109167For C programs:
110168
111169 - We use tabs to indent, and interpret tabs as taking up to
@@ -149,7 +207,7 @@ For C programs:
149207 of "else if" statements, it can make sense to add braces to
150208 single line blocks.
151209
152- - We try to avoid assignments inside if() .
210+ - We try to avoid assignments in the condition of an "if" statement .
153211
154212 - Try to make your code understandable. You may put comments
155213 in, but comments invariably tend to stale out when the code
@@ -177,6 +235,88 @@ For C programs:
177235 - Double negation is often harder to understand than no negation
178236 at all.
179237
238+ - There are two schools of thought when it comes to comparison,
239+ especially inside a loop. Some people prefer to have the less stable
240+ value on the left hand side and the more stable value on the right hand
241+ side, e.g. if you have a loop that counts variable i down to the
242+ lower bound,
243+
244+ while (i > lower_bound) {
245+ do something;
246+ i--;
247+ }
248+
249+ Other people prefer to have the textual order of values match the
250+ actual order of values in their comparison, so that they can
251+ mentally draw a number line from left to right and place these
252+ values in order, i.e.
253+
254+ while (lower_bound < i) {
255+ do something;
256+ i--;
257+ }
258+
259+ Both are valid, and we use both. However, the more "stable" the
260+ stable side becomes, the more we tend to prefer the former
261+ (comparison with a constant, "i > 0", is an extreme example).
262+ Just do not mix styles in the same part of the code and mimic
263+ existing styles in the neighbourhood.
264+
265+ - There are two schools of thought when it comes to splitting a long
266+ logical line into multiple lines. Some people push the second and
267+ subsequent lines far enough to the right with tabs and align them:
268+
269+ if (the_beginning_of_a_very_long_expression_that_has_to ||
270+ span_more_than_a_single_line_of ||
271+ the_source_text) {
272+ ...
273+
274+ while other people prefer to align the second and the subsequent
275+ lines with the column immediately inside the opening parenthesis,
276+ with tabs and spaces, following our "tabstop is always a multiple
277+ of 8" convention:
278+
279+ if (the_beginning_of_a_very_long_expression_that_has_to ||
280+ span_more_than_a_single_line_of ||
281+ the_source_text) {
282+ ...
283+
284+ Both are valid, and we use both. Again, just do not mix styles in
285+ the same part of the code and mimic existing styles in the
286+ neighbourhood.
287+
288+ - When splitting a long logical line, some people change line before
289+ a binary operator, so that the result looks like a parse tree when
290+ you turn your head 90-degrees counterclockwise:
291+
292+ if (the_beginning_of_a_very_long_expression_that_has_to
293+ || span_more_than_a_single_line_of_the_source_text) {
294+
295+ while other people prefer to leave the operator at the end of the
296+ line:
297+
298+ if (the_beginning_of_a_very_long_expression_that_has_to ||
299+ span_more_than_a_single_line_of_the_source_text) {
300+
301+ Both are valid, but we tend to use the latter more, unless the
302+ expression gets fairly complex, in which case the former tends to
303+ be easier to read. Again, just do not mix styles in the same part
304+ of the code and mimic existing styles in the neighbourhood.
305+
306+ - When splitting a long logical line, with everything else being
307+ equal, it is preferable to split after the operator at higher
308+ level in the parse tree. That is, this is more preferable:
309+
310+ if (a_very_long_variable * that_is_used_in +
311+ a_very_long_expression) {
312+ ...
313+
314+ than
315+
316+ if (a_very_long_variable *
317+ that_is_used_in + a_very_long_expression) {
318+ ...
319+
180320 - Some clever tricks, like using the !! operator with arithmetic
181321 constructs, can be extremely confusing to others. Avoid them,
182322 unless there is a compelling reason to use them.
@@ -264,6 +404,15 @@ For Python scripts:
264404 documentation for version 2.6 does not mention this prefix, it has
265405 been supported since version 2.6.0.
266406
407+ Error Messages
408+
409+ - Do not end error messages with a full stop.
410+
411+ - Do not capitalize ("unable to open %s", not "Unable to open %s")
412+
413+ - Say what the error is first ("cannot open %s", not "%s: cannot open")
414+
415+
267416Writing Documentation:
268417
269418 Most (if not all) of the documentation pages are written in the
0 commit comments