The Psychology of Quality and More

C Style: Standards and Guidelines (contents)

CHAPTER 4 : Commenting

PART 2 : COMMENTING AND NAMING

CHAPTER 4 : Commenting
4.1 Commenting fundamentals
4.2 Comment types
4.3 Header comments
4.4 File Header comment
4.5 Function header comments
4.6 Block comments
4.7 Trailing comments
4.8 Commenting data
4.9 The preprocessor and comments
4.10 Summary 

<--Prev page | Next page -->

4.5 Function header comments

When a reader starts to read the function code, he should already have a very good idea of what it is does, how it does it, and what problems he might meet. The function header comment fulfils this need.

4.5.1 Describe the purpose

The name of the function is probably the most succinct description of its purpose. An additional brief description of the action of the function is usually very helpful in clarifying its use.

4.5.2 Describe the inputs and outputs

A function usually processes inputs to create outputs. Describing these inputs and outputs is a clear hint as to what is being done in the function. Inputs include not only parameters, but also global variables and (possibly) constants. Outputs include parameters, global variables and function returns. Describing output values, either explicitly or by reference to where they are defined, helps the user who is following a call to this function. Similarly, describing expectations and limitations on inputs can be helpful.

4.5.3 Describe the process

Describing how the function does what it does, particularly where it uses a complex algorithm or process, can help the user understand the intended action of the code.

This section is often used for a complete pseudo-code description of the code below, sometimes with line numbers which are keyed to commented numbers in the code:

Pseudo-code description in function header:

* [2] find employee number

* [3] extract and filter out current salary

...

In-line comment used to key to header comment:

for ( EmpNo = 0; EmpNo < NofEmployees; EmpNo++ ) /*[2]*/

...

..or, copying or moving the entire comment into the code:

/* [2] find employee number */

for ( EmpNo = 0; EmpNo < NofEmployees; EmpNo++ )

...

The danger of including pseudo-code in the header is that it can easily fall into disrepair (if you fix a bug in the code, will you also fix it in the pseudo-code?).

4.5.3 Describe the external context

Describing the external context of the function, in terms of the called/calling functions may be desirable, although it can be very difficult to maintain. A good cross-referencing tool is often adequate.

4.5.4 Describe the historical context

Each time the function is changed (after the code is 'frozen'), a note should be included describing the change. This may include columns for the internal defect/fix number, the date the change was made, the name (or initials) of the person making the change, and brief details of the change. The code may be keyed to these notes by using fix reference comments.

Fix note in header:

* FX14326  22Jan99  JR     Fix: backspace at character zero in
*                          keyboard buffer disallowed!

 

Matching fix in code:

    if ( (CharNo == 0) && (Ch == BS) )                   /*FX14326*/
        Beep();                                          /*FX14326*/

------------------------------------------------------------------------->

Keeping this information in the code is being very explicit about changes, and may even include old code which is 'commented out' (see 4.9.1). A simpler approach is to extract this when required from the version control system.

4.5.5 Give any other help you can

In a similar manner to file header comments, items that do not easily fit into any of the given categories, such as further warnings, hints, assumptions, limitations, etc. which will help the reader understand the file, can be put into a 'notes' section.

4.5.6 Examples of function header comment

Using the above guidelines, a standard function header may be derived:

/*******************************************************************
* NAME :            int KB_GetLine(pKbdBuf, MaxChars)
*
* DESCRIPTION :     Input line of text from keyboard
*
* INPUTS :
*       PARAMETERS:
*           int     MaxChars                max chars to read before beeping
*       GLOBALS :
*           struct  Terminal                Terminal description (in termdata.h)
*                   char    .BackspaceCode  Code for backspace
*                   char *  .CharSet        keyboard conversion tables
* OUTPUTS :
*       PARAMETERS:
*           char    * pKbdBuf               -> buffer for keyboard chars
*       GLOBALS :
*            None
*       RETURN :
*            Type:   int                    Error code:
*            Values: VALID_DATA             valid read
*                    KB_BAD_DATA            invalid kbd data
*                    KB_DISCONNECTED        keyboard not present
* PROCESS :
*                   [1]  Clear keyboard buffer
*                   [2]  Do
*                   [3]    Get character
*                   [4]    Translate characters
*                   [5]  Until CR or buffer full
*
* NOTES :           Unknown characters returned as '*'
*                   Backspace is the only editing allowed.
* CHANGES :
* REF NO    DATE    WHO     DETAIL
*           12Feb96 AO      Original Code
* FX14326   22Jan99 JR      Fix: backspace at character zero in
*                           keyboard buffer disallowed!
*/

A long function header comment will give a lot of information about the function, but it also takes up a lot of room, and requires a significant effort to write. This may be disproportionate where the function that it describes is small, simple, low-level and infrequently read. In this case, many of the fields in the above example may be omitted to allow the size of the header to be scaled down. A minimum header summarizes the inputs, outputs and the basic process. Note the inclusion of the function declaration within the header.

/*F******************************************************************/

int
KB_GetLine( pKbdBuf, MaxChars )

char    *pKbdBuf;               /* -> buffer for keyboard chars     */
int     MaxChars;               /* max chars to read before beeping */

/*
* PURPOSE : Input line of text from keyboard
*
* RETURN :  VALID_DATA = valid read
*                        (see keyboard.h for the rest)
*
* NOTES :   Unknown characters returned as '*'
*           Backspace is the only editing allowed.
*F*/

<--Prev page | Next page -->