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.17  Preprocessor commands

Preprocessor commands are the poor relations in C. They are seldom viewed as 'real C' statements and have various restrictions on their layout. The result is that they are often treated as being almost invisible, and their layout is ignored.

Preprocessor command layout is constrained in older compilers by the position of the '#', which must be in column 1. Sometimes also, the keyword must immediately follow the '#'.

6.17.1  Preprocessor comparisons

Preprocessor comparisons (#if, #ifdef) with everything left-justified are difficult to read, as the lack of indentations makes the nesting level unclear:

#ifdef DEBUG
int     DebugLevel;
#ifdef TRACE
#define TRACKING 1
#else
#define TRACKING 0
#endif
#endif

Compilers often parse the '#' separately from the keyword, allowing indentation to be used for preprocessor comparisons:

#ifdef DEBUG
    int     DebugLevel;
#   ifdef TRACE
#       define TRACKING 1
#   else
#       define TRACKING 0
#   endif
#endif

ANSI C removes all restrictions on the positioning of the '#' and its keyword.

6.17.2  Constants

Constants are similar to data definitions, and can be laid out similarly, using vertical alignment:

#define PACKET_SIZE     20
#define BUF_SIZE_MAX    256
#define WIN_MASK        0x0F00

‘enum’s are often declared on a single line, especially where their meaning needs no comment:

enum CAR_MAKER { FORD, JAGUAR, VOLKSWAGON };

If there are a lot of items, or if comments are needed, then the vertically aligned layout may be used:

enum CAR MAKER
{
    FORD,           /* US companies */
    GM,
    JAGUAR,         /* UK companies */
    ROVER,
...
};

6.17.3  Macros

Macros are similar to function definitions, and can be laid out similarly, using the principle of 'one action per line' with the continuation character tabbed out of the way of the code:

#define TRACE_IN(FnName)                                   \
        {                                                  \
            if ( TRACKING )                                \
                printf("Trace Enter: %s\n", (FnName));     \
            else if (DEBUGGING)                            \
                DebugPush("Entering Function:", (FnName))  \
        }

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

For simple macros which perform only one or two actions, this may considered to be too complex, and keeping it to a single line may be acceptable.

<--Prev page | Next page -->