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.4 File Header comment

When a reader first picks up a listing, or edits a source file, the first thing that he sees is the file header comment at the start of the file. This should help him start to understand what the file is for, what is in it, what it does, why it does it, etc.

You can help the reader by describing the internal, external and historical context of the file in the sections of this header comment.

4.4.1 Describe the internal context

A simple prose description of what this file contains indicates the internal context. If the file is functionally cohesive, then this is simply a description of the basic function performed or the items contained.

A list of the functions in the file, particularly the public functions, makes a clear statement of what that this file does, possibly with a brief description of their actions. This is a potentially useful piece of information which is helpful to have this early in the file. However, it may be preferable not to duplicate the list of function declarations which will probably appear not long after the end of the header comment (particularly if this 'contents list' is in a standard place).

In the same way, any global data that is defined in this file may be briefly described. This is important because global data is an area where many bugs occur.

4.4.2 Describe the external context

Putting the filename at the start of the header comment makes sure that the reader of the printed listing can find the original source file.

The file may be a part of a group of files which constitute a logical module. The module may be named, as may any other files in the module group.

The file may have links with other external items, a reference to which may help the reader understand/fix/enhance/etc. the code. These could include:

• File/function names where items defined here are referenced elsewhere
• File/function names where items referenced here are defined elsewhere
• Design references
• Documentation references

The danger of cross-referencing, however, is that it can become out of date when other files are changed. Where possible, a cross-reference tool should be used instead.

4.4.3 Describe the historical context

Information on the origins and modifications to the file helps the reader to understand the code, particularly if he has several versions of the file.

If you are proud of your work (and you should be!) your name will help the reader locate you for any questions he may have. Even when you are unavailable, by knowing who you are, he can be prepared for the nuances of your technique.

Each time the file is changed (after the code is 'frozen'), a note should be included describing the change. This may include columns for:

• A reference to changes made, such as defect numbers, fix numbers, etc. If a fix spans several files, then the changes may be linked by the common fix number.
• The date the change was made.
• The name (or initials) of the person making the change.
• The version of the program being fixed.
• Brief details of the change. It is usually better to provide the fine detail of the change nearer to where it is implemented. To do this whilst avoiding duplication, simply put a cross-reference here to the changed item (eg. use name of the function which is changed).

4.4.4 Give any other help you can

Some helpful information does not easily fit into any of the given categories. Such information could contain further warnings, hints, assumptions, limitations, etc. which will help the reader understand the file. It is also a good idea to add a copyright statement.

4.4.5 Example of file header comment

The above guidelines can be used to derive a standard file header comment. As with other standards, it will vary according to organizational needs, but should be consistent at least for one project. A typical layout might be:

/*H**********************************************************************
* FILENAME :        fmcompres.c             DESIGN REF: FMCM00
*
* DESCRIPTION :
*       File compression and decompression routines.
*
* PUBLIC FUNCTIONS :
*       int     FM_CompressFile( FileHandle )
*       int     FM_DecompressFile( FileHandle )
*
* NOTES :
*       These functions are a part of the FM suite;
*       See IMS FM0121 for detailed description.
*
*       Copyright A.N.Other Co. 1990, 1995.  All rights reserved.
*
* AUTHOR :    Arthur Other        START DATE :    16 Jan 99
*
* CHANGES :
*
* REF NO  VERSION DATE    WHO     DETAIL
* F21/33  A.03.04 22Jan99 JR      Function CalcHuffman corrected
*
*H*/

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

<--Prev page | Next page -->