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.16  Function declaration

A function declaration, particularly when it is also a definition, needs to clearly show its purpose, and the meaning of its parameters.

6.16.1  Original or ANSI

The function declaration is another major area where the ANSI standard changes the original layout (although ANSI still allows this).

/* original C */
int
GetKeyPress( pBuffer, CharsToGet ) ;

char    *pBuffer;               /* address for got chars        */
int     CharsToGet;             /* Number of chars required     */

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

This shows the function as it is called, and allows each parameter to be described afterwards. However, it has the redundancy of naming the parameters twice, and requires looking back and fore to correlate their position and type. This can be addressed by using ANSI function prototypes:

/* ANSI C */
int
GetKeyPress( char *pBuffer, int CharsToGet );

This is more concise, but is more likely to overshoot the line and makes commenting of the parameters more difficult. A 'comb' layout can be used to address this problem:

int
GetKeyPress(
    char    *pBuffer,                /* address for got chars     */
    int     CharsToGet );            /* number of chars required  */

6.16.2  Function reference declarations

Where the function is not being defined, such as in extern declarations, it is being explicit to name the identifiers, even though they are not required:

extern  int     GetKeyPress( char *pBuffer, int CharsToGet );

This gives extra information to the reader about what GetKeyPress does, albeit at an increased maintenance cost.

6.16.3  Function type

The function type tends to obscure the function name, which can be inconvenient when searching for a particular function:

struct WINDOW *FindWindow( int WinHandle );

The type and the function name can be separated by putting the type on the previous line. The return type is now clear and the function name is easily found:

struct WINDOW *
FindWindow( int WinHandle );

A danger with this style is that the type may be missed (for example if it is off-screen) and the declaration interpreted as returning an int.

<--Prev page | Next page -->