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.8 Commenting data

Discovering what uncommented code does can be difficult, although by careful tracing a fair guess can often be made. Data, on the other hand, does not do anything. Actions are performed on it and because of it, but not by it. Discovering the purpose of uncommented data can be difficult, especially if it is badly named and widely used. For commenting purposes then, it can be considered as 'complex code', and block and trailing comments used to describe it.

4.8.1 Comment on usage

Data is ideally described by the symbol name given to it. Unfortunately, however, even when the name makes complete sense in the context of the program, the reader can still be left asking, "Yes, but what is it for?". Take, for example, the following:

int     StdFlex;

This may read as 'standard flex', which may be an intermediate factor in an calculation. It is difficult to understand what this item is for when it is defined. It may also be difficult to determine what it is for in use.

StdFlex += FlexFactor( Plastic.Flex );

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

A comment on a data definition helps clarify the intent for its usage, and can also help the reader to understand its actual usage.

int     StdFlex;      /* Intermediate value for flex calculation */
...
/* update intermediate flex factor */
StdFlex += FlexFactor( Plastic.Flex );

Note that as the data definition extends less across the page than executable code, its comment start column can be further to the left.

4.8.2 Comment on values

Where the contents of a variable is constrained, either by range or by a limited set of values, it helps the reader to understand its use if some indication of the possible values is included in the comment.

int     ParaLen;    /* chars in current para < PARA_LEN_MAX        */

int     LockType;   /* lock manufacturer = L_YALE, L_CHUBB, etc.   */

The problem with this method is one of maintenance. If the possible values of the variable change, then the comment becomes wrong, and could confuse.

4.8.3 Comment all data declarations

The decision on which data declarations to comment depends on how 'obvious' the usage and possible values are. To the writer of the code, most things are immediately clear; to the reader, most things are not that obvious. Applying the simplicity principle, the solution is to comment all data declarations:

int  StdFlex;        /* Intermediate value for flex calculation */
int  TotFlex;        /* Final flex value                        */

4.8.4 Comment data tables carefully

Even more important than commenting single data items is commenting data tables. Without explanation, a table is a jumble of numbers, etc. Take the following example:

int  AgeFactors[] = { 0, 10, 22, 25, 15, 10, 8, 2 };

What are these 'AgeFactors'? What is the difference between the first and the second elements? Commenting can give the answer. Data tables often require more than half a line of comments, so a block comment is usually a good idea.

/*--------------------------------------------------------------
*   'AgeFactor[AgeBand]' is the correction factor for expected
*   employee performance during each company standard AgeBand.
*   It is used in promotion prospect calculation.
*/
int  AgeFactors[] = { 0, 10, 22, 25, 15, 10, 8, 2 };

Note the helpful hints in this comment:

1. Commenting by example to indicate usage.
2. Comment of where the data might be used gives more hints on its usage.

Comments should similarly be applied to other declarations, such as #define's, structure declarations, etc.

struct SAL_REC            /* Employee salary details  */
{
     int EmpNo;      /* Employee number (4 digits)   */
     int CurrSalary; /* Current annual salary        */
     int TotPaid;        /* Total salary paid this year  */
};

<--Prev page | Next page -->