The Psychology of Quality and More

C Style: Standards and Guidelines (contents)

CHAPTER 6 : Layout

PART 3 : LAYOUT

CHAPTER 6 : Code Layout
6.1 Basic principles of code layout
6.2 Use of Spaces
6.3 Use of blank lines
6.4 Use vertical alignment
6.5 Indentation level
6.6 Line wrapping
6.7 Braces
6.8 Use of parentheses
6.9 Nested single statement
6.10 Empty statements
6.11 'else..if'
6.12 'switch' statements
6.13 'do..while'
6.14 Labels
6.15 Data declarations
6.16 Function declaration
6.17 Preprocessor commands
6.18 Summary

<--Prev page | Next page -->

6.7  Braces

Brace layout is probably the most noticeable element of the style of a C program. There are several common styles of brace usage which can cause significant confusion if mixed:

if ( LineStatus == LINE_OPEN ) {
    while ( CheckLineLevel() == LEVEL_OK )
    {
        while ( (Ch = ReadLine()) != EOF )
            {
            if ( Ch == CH_REVERSE) {
                ReverseLine();
            }
            }
    }
}

------------------------------------------------------------

It is arguable that braces are an 'unnecessary' part of the layout and that indentation alone is enough to show nesting. Against this is the argument that braces follow the principle of explicitness in laying out a block, clearly showing the start and the end.

These arguments play a part in the philosophy behind the three most common styles in current usage:

Kernel style

This is also known as the 'Kernighan and Ritchie' or 'K&R' style, as it is that used in 'The C Programming Language', and is typified by:

if ( PageWidth > PaperWidth ) {
    SetPageWidth( PaperWidth );
    TellUser( MSG_PAGE_CHANGED );
}

The opening brace is on the same line as the statement which creates the compound statement. The statements on following lines are indented, and the closing brace is not indented - i.e. it is directly below the original statement.

As the 'original' style, this is widely used, although it does have some disadvantages. It can be difficult to visually match the closing brace with the opening statement, especially if the block is long, and even more so if it stretches across a page boundary. The reader is then forced to match braces, which is difficult when they are not vertically aligned. The opening brace, especially, is not that easy to spot.

Consider also where the comparison is complex and must wrap to the next line:

if ( PageWidth > PaperWidth || PageWidth < PG_MIN_WIDTH ||
    IsNewDocument() ) {
    SetPageWidth( PaperWidth );
    TellUser( MSG_PAGE_CHANGED );
}

------------------------------------------------------------

It now becomes less clear as to where the comparison ends and the compound statement starts.

Note that Kernighan and Ritchie acknowledge that there are other, equally valid, styles, and that standardizing on one style is the most important aspect of using braces.

Allman style

The Allman style differs from the Kernel style in the placing of the opening brace directly below the start of the statement which creates the compound statement:

if ( PageWidth > PaperWidth )
{
    SetPageWidth( PaperWidth );
    TellUser( MSG_PAGE_CHANGED );
}

The braces are now easily matched, and, being on lines by themselves, are easily spotted. Consider now the case of the complex, line-wrapping comparison:

if ( PageWidth > PaperWidth || PageWidth < PG_MIN_WIDTH ||
    IsNewDocument() )
{
    SetPageWidth( PaperWidth );
    TellUser( MSG_PAGE_CHANGED );
}

It is now immediately clearer where the comparison ends and where the compound statement begins. The single brace after the if statement clearly delimits the start of the compound statement, and provides a natural break between the comparison and the block (although this is at the cost of an extra line, reducing the conciseness of the code).

As may have been noticed, this is the style used in this book.

This style is often favoured by programmers who have used other block structured languages, such as Pascal.

Whitesmiths style

The Whitesmiths style is a variation on the Allman style, where the braces are now indented to the same column as the rest of the compound statement:

if ( PageWidth > PaperWidth )
    {
    SetPageWidth( PaperWidth );
    TellUser( MSG_PAGE_CHANGED );
    }

In this style the indentation of the whole compound statement is more consistent with the indentation of a single statement, where the whole statement is indented. It also allows first level statements of a function to start at the first column, saving an unnecessary indentation or 'exception to the rule' for other styles:

int OpenNet( char *Password );
{
if ( OpenLine() != LINE_OPEN )
    return( NET_CLOSED )
else
    {
    WritePassword( Password );
    return( NET_OPEN )
    }
}

If the Allman (or Kernel) style was used with statements starting in the first column, this could result in two closing braces in the same column:

int OpenNet( char *Password );
{
if ( OpenLine() != LINE_OPEN )
    return( NET_CLOSED )
else
{
    WritePassword( Password );
    return( NET_OPEN )
}
}

Brace Variations

There are other variations on the above styles, such as modifying the Allman style to recover the lost line after the initial statement, (although this makes line insertion less easy):

if ( PageWidth > PaperWidth )
{   SetPageWidth( PaperWidth );
    TellUser( MSG_PAGE_CHANGED );
}

..or half-indenting the braces..

if ( PageWidth > PaperWidth )
  {
    SetPageWidth( PaperWidth );
    TellUser( MSG_PAGE_CHANGED );
  }

Braces are used not only in compound statements but also in such as struct's, union's and enum's. The style used for statements can be simply carried over to these declarations and definitions.

<--Prev page | Next page -->