CodingGuidelines: on splitting a long line
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
May 2, 2014 at 13:42 UTC
f26443da0449c459dab8b91d963bd91dd4335657
1 file changed
+55
Documentation/CodingGuidelines
+55
@@ -249,6 +249,61 @@ For C programs:
249
Just do not mix styles in the same part of the code and mimic
250
existing styles in the neighbourhood.
251
252
+ - There are two schools of thought when it comes to splitting a long
253
+ logical line into multiple lines. Some people push the second and
254
+ subsequent lines far enough to the right with tabs and align them:
255
+
256
+ if (the_beginning_of_a_very_long_expression_that_has_to ||
257
+ span_more_than_a_single_line_of ||
258
+ the_source_text) {
259
+ ...
260
+
261
+ while other people prefer to align the second and the subsequent
262
+ lines with the column immediately inside the opening parenthesis,
263
+ with tabs and spaces, following our "tabstop is always a multiple
264
+ of 8" convention:
265
+
266
+ if (the_beginning_of_a_very_long_expression_that_has_to ||
267
+ span_more_than_a_single_line_of ||
268
+ the_source_text) {
269
+ ...
270
+
271
+ Both are valid, and we use both. Again, just do not mix styles in
272
+ the same part of the code and mimic existing styles in the
273
+ neighbourhood.
274
+
275
+ - When splitting a long logical line, some people change line before
276
+ a binary operator, so that the result looks like a parse tree when
277
+ you turn your head 90-degrees counterclockwise:
278
+
279
+ if (the_beginning_of_a_very_long_expression_that_has_to
280
+ || span_more_than_a_single_line_of_the_source_text) {
281
+
282
+ while other people prefer to leave the operator at the end of the
283
+ line:
284
+
285
+ if (the_beginning_of_a_very_long_expression_that_has_to ||
286
+ span_more_than_a_single_line_of_the_source_text) {
287
+
288
+ Both are valid, but we tend to use the latter more, unless the
289
+ expression gets fairly complex, in which case the former tends to
290
+ be easier to read. Again, just do not mix styles in the same part
291
+ of the code and mimic existing styles in the neighbourhood.
292
+
293
+ - When splitting a long logical line, with everything else being
294
+ equal, it is preferable to split after the operator at higher
295
+ level in the parse tree. That is, this is more preferable:
296
+
297
+ if (a_very_long_variable * that_is_used_in +
298
+ a_very_long_expression) {
299
+ ...
300
+
301
+ than
302
+
303
+ if (a_very_long_variable *
304
+ that_is_used_in + a_very_long_expression) {
305
+ ...
306
+
307
- Some clever tricks, like using the !! operator with arithmetic
308
constructs, can be extremely confusing to others. Avoid them,
309
unless there is a compelling reason to use them.