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.2  Use of Spaces

Spaces, for the most part, are not really necessary in C, and it is possible to write code without using them:

if(Wgt.Hgt>((StdHgt+WGT_OFFSET)*WGT_CRCTN))
    Wgt->Size=(ActSize>StdSize)?StdSize:NewSize-OldSize;

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

The main use of spaces is to increase the readability of the code. Thus we could put a space between all tokens in the above code:

if ( Wgt . Hgt > ( ( StdHgt + WGT_OFFSET ) * WGT_CRCTN ) )
    Wdt -> Size = ( ActSize > StdSize ) ? StdSize : NewSize - OldSize ;

This makes the individual tokens clearly identifiable, but some items are now too dissociated. A balance must be struck between using space for readability and not spacing items to maintain a close association. There is also a horizontal cost of using spaces within a line which can cause the line to wrap and possibly become less readable.

A simple set of rules which may be used for spacing tokens is:

1. No spaces within object references.
2. No spaces between unary operators and their operands (but space on other side).
3. All other binary operators have an equal number of spaces either side.

Individual instances, which may include exceptions to the above rules, are discussed below.

6.2.1  Spacing object references

A structure or array reference, although made up of identifiers and tokens, is a closely associated reference to a single object. So do not space structure and array references : ., ->, []:

Para.Length, Window->Size, EmpName[10]

6.2.2  Spacing unary operators

Unary operators are closely associated with one token, thus do not put a space between unary operators and their operand: !,  ~, ++, --, -, * (pointer indirection), &, (casts), sizeof:

!DoorIsOpen, ~PortEnables, WgtNo++, --WgtNo, -10,
*pFirstName, &FieldSize, (int)ParaStatus, sizeof(int)

Do put a space on the side away from the operand, as this helps to make the association with its token clear. It also avoids 'gotchas', for example where '/*' is taken as the start of a comment:

*Current = *Volts/*Resistance;    /* *Current = *Volts ? */

6.2.3  Spacing binary operators

Binary operators are quite closely associated with their operands, but they can be seen more clearly when they are spaced either side - particularly when there are long identifier names and other operators about. These operators include: +, -, *, /, %, >>, <<, <, <=, =>, >, ==, !=, &, |, &&, ||, ? :, =, +=, etc.

WordNo = FirstWordNo + *CurrWordOffset;

It might be permissible to not use spaces in situations to emphasize precedence, although this is complicating a simple rule, and there is a danger of incorrect usage causing misunderstanding:

if ( WdStart+WdOffset > MAX_OFFSET*WdSize )   /* this is ok   */

..but..

if ( WdStart+WdOffset / WdSize > MAX_OFFSET ) /* this is not! */

6.2.4  Spacing comma and semicolon

The comma, ',', and the semicolon, ';', are more closely associated (albeit loosely) with the previous item than the following item. Thus, they may have no space before and a space after. Note that this is the same usage as in the written form of the English language:

for ( i = 0, j = 0; i < WGT_MAX; i++, j++ )

Applying all of the above rules to the original example in 6.2 now gives:

if ( Widget.Hgt > ((StdHgt + WGT_OFFSET) * WGT_CORRN) )
    Widget->Size = (ActSize > StdSize) ? StdSize : NewSize - OldSize;

6.2.5  Spacing parentheses

In all parenthesized items, the contents can be made to stand out more by putting a space after the '(' and before the ')'. In nested parentheses, the inner sets of parentheses may not be spaced, to differentiate them from the outer set of parentheses. In any case by always matching the spacing on any pair of parentheses, matching pairs are made easier to identify:

if ( CurrPage > (FirstPage - LastPage) )

..not..

if ( CurrPage > (FirstPage - LastPage ))

It is similarly useful to try to match the spacing on the outside of parentheses, although this is not always possible with nested sets of parentheses:

(FirstPage + (CurrPage - LastPage))

The first parenthesis of a function call is closely associated with the function name, helping to identify it as a function. Also, if it was actually a macro, the parenthesis would have to match the macro. Thus, do not put a space between a function name and its first parenthesis:

CalcWindowSize( Window );

6.2.6  Spacing keywords

Keywords are not functions, and may be shown to be such by spacing them out:

if ( DiscIsFull )

Possible exceptions to this are return and sizeof:

'return'

The return keyword is followed by an optional expression:

return LineStatus || COLLISION_MASK;

It is common to use parentheses to more clearly delimit the return'ed expression, even when returning a single value. return is often viewed (erroneously, but harmlessly) as being a function, which would suggest that there be no space after it. The reader may be reminded of its keyword status by retaining the following space:

return ( LineStatus || COLLISION_MASK );

'sizeof'

The sizeof keyword has different rules for objects and types. Objects do not need parenthesizing, but types do:

sizeof Para   ..but..   sizeof (int)

This subtlety can cause confusion and error. The simplest approach is to use parentheses on both. In any case, sizeof is a unary operator, and by the arguments above (see 6.2.2) a space should not be put between an unary operators and its operand. To do this, sizeof objects needs to use parentheses as separators:

sizeof(Para)  ..and..   sizeof(int)

<--Prev page | Next page -->