Re: [boost] Coding guidelines: 5.1

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2001-07-07 17:44:27

----- Original Message -----
From: "Douglas Gregor" <gregod_at_[hidden]>

> 5.1 states "Use a separate line for opening and closing braces". In "Code
> Complete", Steve McConnell considers the following three styles:
>
> // 1
> if (cond) {
>   stmt1;
>   stmt2;
> }
>
> // 2
> if (cond)
> {
>   stmt1;
>   stmt2;
> }
>
> // 3
> if (cond)
>   {
>   stmt1;
>   stmt2;
>   }
>
> 5.1 suggests style #2, which is the only one of the three that McConnell
says
> _not_ to use, because it violates his "Fundamental Theorem of Formatting."
> Essentially, the formatting doesn't fit the logic: without whitespace both
> above an below the entire code snippet, one can't tell that the block is
part
> of the if statement. Code like this:
>
> // A
> foo = wibble + bar;
> {
>   stmt1;
>   stmt2;
> }
>
> looks very similar to #2, but there is no relation between the block and
the
> line before it. Throw in an identifier that looks like a statement
(for_each,
> perhaps?) and it becomes more confusing. While I've not seen code like "A"
> often in C++ (it's more common in C when the programmer needs a temporary
> variable), it would be used more often when using the
> resource-acquisition-is-initialization methodology.

And, optimizing for the most common case, I would say that you should add a
blank line before the opening brace of blocks that are not part of and if,
else, while, or do clause.

IMO this "theorem of formatting" is an example of overblown application of
formalism where it doesn't belong. I actually find his attempt to justify
one bracing style over another in terms of a "fundamental theorem" slightly
offensive.

I think ultimately, the choice of bracing style is a religious issue.
Anyone who has done a little user-interface design knows that you can apply
as many theorems as you want, but the user is always right. If a user finds
your perfectly logical design difficult, the design is wrong, no matter how
well-worked-out it might be. In this case, the user is me ;-)

Indented closing braces are difficult for me (I think because they make it
harder to find the end of a block), and they just look wrong. I'm not
ashamed to admit that it comes down to personal taste and what works for me.

> McConnell also cites a study that found no statistically significant
> difference between #1 and #3 regarding readability and understandability
of
> code. Between these two it is a matter of personal preference, but I think
> that there is good reason not to accept the style proposed by 5.1.
>
> I personally would opt for #1 because
> a) doesn't waste vertical space
> b) more common historically

Style 1 (K&R) often leads to that is unreadable due to its vertical density
(see http://www.boost.org/boost/graph/minimum_degree_ordering.hpp) for some
examples of this.

-Dave