Re: [boost] Coding guidelines: 5.1

From: Douglas Gregor (gregod_at_[hidden])
Date: 2001-07-07 21:28:20

On Saturday 07 July 2001 06:44, you wrote:
> ----- 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.

It's religious, and I won't persist. I found McConnell's argument 
interesting, but I was already on the K&R side of the fence. An argument is 
always better when it agrees with your own opinion :)

I found closing braces to be a problem regardless of the style chosen. Even 
if the opening brace is on the screen it can be tough to track. Meta-left 
arrow saves the day for emacs users.

> > 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

Personally, I've never found the K&R style to be a limitation in writing 
readable code. It helps in some cases to force one to rethink a multiline if 
condition or for header, i.e.,

if (cond &&
    cond2) {
}

looks absolutely terrible, so you give cond && cond2 a pretty name and 
condense it into one line. 

Nobody's mind is going to change; I wanted to gauge the resistence to such a 
change in the hope of agreeing with some part of the Boost style <g>

        Doug