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.1  Basic principles of code layout

There are several broad principles that can be used to guide selection and application of code layout standards.

6.1.1  Lay out code in chunks

The chunking principle (see 2.8) suggests that code should be written as a hierarchy of chunks, each containing a limited number of sub-chunks. This principle can be used right down to the atomic level.

The smallest effective chunk is a single token (e.g. identifier, operator, keyword). These are built into larger chunks such as parenthesized items, single comparisons, etc. which are in turn built into larger expressions and statements. For example, each of the following lines can be read as one chunk:

1.   CursX
2.   (CursX < LineLen)
3.   (CursX < LineLen) || (KeyVal == NEWLINE)
4.   if ( (CursX < LineLen) || (KeyVal == NEWLINE) )
5.   if ( (CursX < LineLen) || (KeyVal == NEWLINE) ) NewLine();

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

Groups of statements which together perform an identifiable act are also chunks, as are individual functions and complete subsystems. By recognizing chunks and making them stand out, the code can be made more readable.

6.1.2  Use white space wisely

Items which are close together form a visual chunk and have an implied association. If they are separated, then they appear less associated. When an item is between two other items, it will appear more closely associated with the item to which it is positioned closest. Thus white space can be used not only to separate chunks but also to show relationships between chunks.

Spaces and tabs are used to chunk horizontally, separating items on a single line. Form feeds and blank lines are used to chunk vertically, separating groups of statements. Tabs also can be used to chunk both horizontally and vertically (items on well separated lines which start in the same column can have an implied association).

White space, however, is not without its cost. Spaces and tabs have a cost in horizontal space, where there are typically only 80 characters available per line. Blank lines have a cost in vertical space, where there are typically only 24 lines per screen or around 60 lines per page. When the code is forced to wrap, horizontally or vertically, the readability of the code is usually decreased, although careful management of wrapping can reduce (or sometimes even improve) this problem.

There are two common schools of thought about the use of white space. The conservative school aims to minimize its use, whilst the liberal school is more generous in its use. This book tends towards the more liberal school, aiming to use space to increase readability and to show relative association, but without causing excessive explosion of the text.

6.1.3  One action per line

Putting one 'action' per line helps to make each line a recognizable and regular sized chunk of information. Consider:

if ( CharCount > LineLen) NewLine();

This contains two actions, the evaluation of the comparison and of the subsequent statement. Separating these actions onto individual lines:

if ( CharCount > LineLen )
    NewLine();

A simple rule for identifying 'actions' is to look for complete expressions.

When a single statement continues onto the following line, this principle can be used to determine wrap-points by identifying separate 'sub-actions' within the line.

Exceptions to this rule may be permissible when the actions are very closely related and the new layout is as clear, if not clearer, even to a relatively inexperienced programmer:

WordCount = WordLen = 0;
...
case DB_HFULL:  TellUser( "Database 50% full" );    break;
case DB_FULL:   FatalError( "Database full!" );     break;
default:        UnknownError( DB_ID, "DB_Write" );  break;

6.1.4  Toothbrushes vs. Combs

When an item is followed by a related group of items, there are two layout possibilities. The 'toothbrush' layout has a handle which sticks out a long way, with the bristles at the end. This makes the handle very visible and easy to find and read:

struct CHAR_TYPE  {
                      unsigned int    FontName;
                      unsigned int    Point;
                  };

However, this causes tramping across the page towards the right margin. A list of such items may also result in uneven, less readable, indentation. A more common approach is to use the 'comb' layout, which has only a small handle, with the bristles in a standard position below it:

struct CHAR_TYPE
{
    unsigned int    FontName;
    unsigned int    Point;
};

<--Prev page | Next page -->