How we change what others think, feel, believe and do
CHAPTER 4 : Commenting
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:
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:
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:
And the big