maint: document dislike of mismatched if/else bracing

* docs/hacking.html.in (Curly braces): Tighten recommendations to
disallow if (cond) one-line; else { block; }.
* HACKING: Regenerate.
Suggested by Daniel P. Berrange.

diff --git a/HACKING b/HACKING
index d64670900c6a423967f6f4db540ca8ecf0a388c8..4a71b370cfa2ac2480eebcf3c236be73e2da3371 100644 (file)
--- a/HACKING
+++ b/HACKING
@@ -161,33 +161,42 @@ Do this, instead:
 
 However, there is one exception in the other direction, when even a one-line
 block should have braces. That occurs when that one-line, brace-less block is
-an "else" block, and the corresponding "then" block *does* use braces. In that
-case, either put braces around the "else" block, or negate the "if"-condition
-and swap the bodies, putting the one-line block first and making the longer,
-multi-line block be the "else" block.
+an "if" or "else" block, and the counterpart block *does* use braces. In that
+case, put braces around both blocks. Also, if the "else" block is much shorter
+than the "if" block, consider negating the "if"-condition and swapping the
+bodies, putting the short block first and making the longer, multi-line block
+be the "else" block.
 
   if (expr) {
       ...
       ...
   }
   else
-      x = y;    // BAD: braceless "else" with braced "then"
+      x = y;    // BAD: braceless "else" with braced "then",
+                // and short block last
 
-This is preferred, especially when the multi-line body is more than a few
-lines long, because it is easier to read and grasp the semantics of an
-if-then-else block when the simpler block occurs first, rather than after the
-more involved block:
+  if (expr)
+      x = y;    // BAD: braceless "if" with braced "else"
+  else {
+      ...
+      ...
+  }
 
-  if (!expr)
+Keeping braces consistent and putting the short block first is preferred,
+especially when the multi-line body is more than a few lines long, because it
+is easier to read and grasp the semantics of an if-then-else block when the
+simpler block occurs first, rather than after the more involved block:
+
+  if (!expr) {
     x = y; // putting the smaller block first is more readable
-  else {
+  } else {
       ...
       ...
   }
 
-If you'd rather not negate the condition, then at least add braces:
+But if negating a complex condition is too ugly, then at least add braces:
 
-  if (expr) {
+  if (complex expr not worth negating) {
       ...
       ...
   } else {

diff --git a/docs/hacking.html.in b/docs/hacking.html.in
index 900e2428adb4049bdde9e8e8585ad6359d6f72a4..0d81b0bed1c5419e505eca6179a66f176460f079 100644 (file)
--- a/docs/hacking.html.in
+++ b/docs/hacking.html.in
@@ -209,11 +209,13 @@
     <p>
       However, there is one exception in the other direction, when even a
       one-line block should have braces.  That occurs when that one-line,
-      brace-less block is an <code>else</code> block, and the corresponding
-      <code>then</code> block <b>does</b> use braces.  In that case, either
-      put braces around the <code>else</code> block, or negate the
-      <code>if</code>-condition and swap the bodies, putting the
-      one-line block first and making the longer, multi-line block be the
+      brace-less block is an <code>if</code> or <code>else</code>
+      block, and the counterpart block <b>does</b> use braces.  In
+      that case, put braces around both blocks.  Also, if
+      the <code>else</code> block is much shorter than
+      the <code>if</code> block, consider negating the
+      <code>if</code>-condition and swapping the bodies, putting the
+      short block first and making the longer, multi-line block be the
       <code>else</code> block.
     </p>
 
@@ -223,31 +225,41 @@
       ...
   }
   else
-      x = y;    // BAD: braceless "else" with braced "then"
+      x = y;    // BAD: braceless "else" with braced "then",
+                // and short block last
+
+  if (expr)
+      x = y;    // BAD: braceless "if" with braced "else"
+  else {
+      ...
+      ...
+  }
 </pre>
 
     <p>
-      This is preferred, especially when the multi-line body is more than a
+      Keeping braces consistent and putting the short block first is
+      preferred, especially when the multi-line body is more than a
       few lines long, because it is easier to read and grasp the semantics of
       an if-then-else block when the simpler block occurs first, rather than
       after the more involved block:
     </p>
 
 <pre>
-  if (!expr)
+  if (!expr) {
     x = y; // putting the smaller block first is more readable
-  else {
+  } else {
       ...
       ...
   }
 </pre>
 
     <p>
-      If you'd rather not negate the condition, then at least add braces:
+      But if negating a complex condition is too ugly, then at least
+      add braces:
     </p>
 
 <pre>
-  if (expr) {
+  if (complex expr not worth negating) {
       ...
       ...
   } else {