Braces and Indenting: You’re Doing it Wrong

Java, C++, Objective-C, and C# all use braces ( { and } ) to delineate the beginning and end of blocks of code. Over the years, several styles have evolved, with the worst of them dominating the literature. Once you see The Light you’ll wonder how we ever let this get out of hand.

Before we begin, let’s remind ourselves what braces are for: They mark the beginning and end of blocks of code. In many contexts a block stands in place of a single statement. It allows us to put two or more statements in a place where a single statement is called for in the grammar. In those contexts a block is functionally equivalent to the single statement it replaces. This will be important in our understanding of the One Right Way to indent.

In other contexts, such as the bodies of functions, surrounding the cases in a switch statement, and surrounding the declarations in a class definition, braces demarcate the contents of the function, switch, and class. For convenience, I’ll refer to any group of lines of code surrounded by braces as a “block”, even though the language definition may not always use that term in every context in which braces are used.

So the the first question is to ask: “To what do the braces belong: the block they surround or the syntactical element (if, for, switch, class etc.) to which the block belongs?”

When braces are used to surround a true block (the else clause of an if statement, for example), it’s clear the braces belong to the block. Together with the lines of code they contain, they replace a single statement.

The implication is that the braces should be indented at the same level as the lines of code in the block they surround, for they are part of that block.

The second question we need to ask is: “Should braces share the line with any other code; either a statement from the block they surround or the statement the block belongs to?”

Clearly we would not format code like this:

    x
    = y
    +
    z
    ;

We might break a very long line into two or more lines, but a short statement should always be on one line. Similarly, we try to avoid code like this:

    x = y + z; if ( x > 10 ) foo(x); bar(z); switch (y) {case 1: x = 2 * y; break; case 2: default: foo(x); break;}

The commonly accepted practice is to put one statement on each line. (There are exceptions but they are rare.) Similarly, I would argue that braces belong on a line by themselves. They are not “inline operators” like + or ==. They do not belong to the statement to their right or left; they surround those statements.

The reason we don’t put two or more statements on one line is that it is more difficult to read. It’s why we break up our thoughts into sentences and paragraphs. It aids in comprehension. The same is true of code. Consider the following:

    if ( x < 10 ) { foo(x);
        bar(y); }

The call to foo(x) belongs to the then-clause because it is inside the brace but it would be easy to glance at the code and assume bar(y) is the only statement executed when the if-condition is true because the call to foo(x) is “hidden” at the end of the if statement.

For this reason I would argue that braces belong on a line by themselves. It is too easy to miss them when they are “hidden” at the end of another line of code. So unless you’re in the habit of writing a dozen statements on one line, it doesn’t make sense to put a brace on the same line as another line of code.

With these two rules (i.e. braces belong to the block they surround and braces belong on a line by themselves), there’s only One Right Way to indent your code:

    if ( x < 10 )
        {
        foo(x);
        bar();
        }
    else
        {
        x += 10;
        foo(x);
        }

Now we can see why the predominant indenting style is so, so wrong:

    if ( x < 10 ) {    // should not be on same line as "if"; should be indented with block
        foo(x);
        bar();
    } else {              // should not be on same line as else (*2); should be indented like block above/below
        x += 10;
        foo(x);
    }                     // should be indented like block above

I realize those of you who grew up doing this wrong and reading all the literature from others who do it wrong will find the One Right Way more difficult to read. But it can be argued that you only find it difficult to read because you’re not accustomed to doing things the One Right Way, while the wrong style as illustrated above is difficult for me to read because it makes no attempt to be logically consistent. This makes it objectively wrong, not just a matter of personal preference.

---

Postscript
In the spirit of unity and the cause of world peace, practitioners of the One Right Way will accept the following style with the hope that those practicing it will see the one small error in their way and with proper mentoring and encouragement, will correct it:

    if ( x < 10 )
    {
        foo(x);
        bar();
    }
    else
    {
        x += 10;
        foo(x);
    }