* docs/hacking.html.in (Curly braces): Tighten recommendations to disallow if (cond) one-line; else { block; }. * HACKING: Regenerate. Suggested by Daniel P. Berrange. ---
since HACKING documents that an else clause should only ever omit braces when the if clause also omitted braces, but an if clause can omit braces even when the else clause requires them. Hmm, I didn't notice that. I really don't like to see braces in else clauses, without also seeing braces in the if, and have been fixing this to add braces whenever I come across it.
Fine by me - how does this look? HACKING | 35 ++++++++++++++++++++++------------- docs/hacking.html.in | 34 +++++++++++++++++++++++----------- 2 files changed, 45 insertions(+), 24 deletions(-) diff --git a/HACKING b/HACKING index d646709..4a71b37 100644 --- 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 900e242..0d81b0b 100644 --- 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 { -- 1.7.3.4