CodingGuidelines: clarify multi-line brace style
There are some "gray areas" around when to omit braces from a conditional or loop body. Since that seems to have resulted in some arguments, let's be a little more clear about our preferred style. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jeff King committed
Jan 17, 2017 at 15:05 UTC
1797dc51766576453c64fd422e25741ead9b2687
1 file changed
+32
-5
Documentation/CodingGuidelines
+32
-5
@@ -206,11 +206,38 @@ For C programs:
206
x = 1;
207
}
208
209
- is frowned upon. A gray area is when the statement extends
210
- over a few lines, and/or you have a lengthy comment atop of
211
- it. Also, like in the Linux kernel, if there is a long list
212
- of "else if" statements, it can make sense to add braces to
213
- single line blocks.
209
+ is frowned upon. But there are a few exceptions:
210
+
211
+ - When the statement extends over a few lines (e.g., a while loop
212
+ with an embedded conditional, or a comment). E.g.:
213
+
214
+ while (foo) {
215
+ if (x)
216
+ one();
217
+ else
218
+ two();
219
+ }
220
+
221
+ if (foo) {
222
+ /*
223
+ * This one requires some explanation,
224
+ * so we're better off with braces to make
225
+ * it obvious that the indentation is correct.
226
+ */
227
+ doit();
228
+ }
229
+
230
+ - When there are multiple arms to a conditional and some of them
231
+ require braces, enclose even a single line block in braces for
232
+ consistency. E.g.:
233
+
234
+ if (foo) {
235
+ doit();
236
+ } else {
237
+ one();
238
+ two();
239
+ three();
240
+ }
241
242
- We try to avoid assignments in the condition of an "if" statement.
243