docs: Adjust contributor guidelines about curly brackets

After recent discussion it looks like curly brackets around one-line
bodies are preferred if the preceding condition is, itself, multiline.

Signed-off-by: Martin Kletzander <mkletzan@redhat.com>

diff --git a/HACKING b/HACKING
index 8f42e512708942f51aa5bf7f70a3f00eeebb1753..0be13bb86f42eb6c93a4fe4fa3de3c9e1b54a042 100644 (file)
--- a/HACKING
+++ b/HACKING
@@ -370,14 +370,20 @@ although use of a semicolon is not currently rejected.
 
 Curly braces
 ============
-Omit the curly braces around an "if", "while", "for" etc. body only when that
-body occupies a single line. In every other case we require the braces. This
-ensures that it is trivially easy to identify a single-'statement' loop: each
-has only one 'line' in its body.
+Omit the curly braces around an "if", "while", "for" etc. body only when both
+that body and the condition itself occupy a single line. In every other case
+we require the braces. This ensures that it is trivially easy to identify a
+single-'statement' loop: each has only one 'line' in its body.
 
-Omitting braces with a single-line body is fine:
+  while (expr)             // single line body; {} is forbidden
+      single_line_stmt();
+
+  while (expr(arg1,
+              arg2))      // indentation makes it obvious it is single line,
+      single_line_stmt(); // {} is optional (not enforced either way)
 
-  while (expr) // one-line body -> omitting curly braces is ok
+  while (expr1 &&
+         expr2)           // multi-line, at same indentation, {} required
       single_line_stmt();
 
 However, the moment your loop/if/else body extends on to a second line, for

diff --git a/docs/hacking.html.in b/docs/hacking.html.in
index b1553a5c5f98a6005f6302a62bcc573566d1d7b8..32ebd8e0ac8d8d98722fdb3db358804504df24c1 100644 (file)
--- a/docs/hacking.html.in
+++ b/docs/hacking.html.in
@@ -462,17 +462,26 @@
 
     <p>
       Omit the curly braces around an <code>if</code>, <code>while</code>,
-      <code>for</code> etc. body only
-      when that body occupies a single line.  In every other case we require
+      <code>for</code> etc. body only when both that body and the condition
+      itself occupy a single line.  In every other case we require
       the braces.  This ensures that it is trivially easy to identify a
       single-<i>statement</i> loop: each has only one <i>line</i> in its body.
     </p>
-    <p>
-      Omitting braces with a single-line body is fine:
-    </p>
 
 <pre>
-  while (expr) // one-line body -> omitting curly braces is ok
+  while (expr)             // single line body; {} is forbidden
+      single_line_stmt();
+</pre>
+
+<pre>
+  while (expr(arg1,
+              arg2))      // indentation makes it obvious it is single line,
+      single_line_stmt(); // {} is optional (not enforced either way)
+</pre>
+
+<pre>
+  while (expr1 &amp;&amp;
+         expr2)           // multi-line, at same indentation, {} required
       single_line_stmt();
 </pre>