The Psychology of Quality and More
CHAPTER 4 : Commenting
4.1 Commenting fundamentals
There are a few basic principles that can be used to guide the use of comments in all situations. We shall consider these before going on to use these principles in specific commenting situations.
4.1.1 Be clear and concise
Comments are intended to help the reader understand the code. They should not be short and cryptic, neither should they be long and woffly! The art of commenting (and it is an art) is to explain, clearly and succinctly, what is happening (and possibly why). Which of the following has the better comment?
DoorStatus = OPEN; /* Clearance unnecessary */
All of these comments explain the effect of the door being open, but the first is too vague whilst the last is over-explicit. There is, somewhere, a balance between trying to be too succinct (or too clever or too lazy) and being too explicit and detailed. This balance, however, is not absolute. One person's idea of a succinct description may quite easily be another person's confusing lack of detail and yet another person's unnecessary explanation of the obvious.
Comments may be made shorter by using abbreviations and selected words from within a sentence, although care must be taken that no ambiguities are introduced, and that the meaning is still immediately clear. Any lack of clarity will cause the reader to context-switch whilst pondering the meaning of the comment:
DoorStatus = OPEN; /* May enter w'out sec. clrnce */
Here, the word 'now' has been dropped without much loss. 'w'out' is a fairly clear abbreviation of 'without'. 'sec.' is ambiguous - it could mean something like 'secondary' or 'secret'. 'clrnce' is fair, but could cause a moment's hesitation ("'Clarence' fits, but no, that's absurd, it must be 'clearance'").
Comments should always add value. They should not just restate what the code does.
DoorStatus = OPEN; /* Door status now open */
As a general rule, shorter comments should paraphrase what is happening, with descriptions of how being put in longer comments.
4.1.2 Ensure comments are correct
It may be obvious, but is still needs to be said: Comments should agree with the code! A wrong comment is like a signpost which points in the wrong direction:
DoorStatus = OPEN; /* Door open, but still secure */ <--WRONG!
Comments often go astray like this when the code is being modified at a later date. The modifier is in a hurry, and just modifies the code without ensuring that the comments are still correct! This can even be done by the maintainer, who is cutting his own team's throat by laying traps to ensnare later maintainers.
There is also a danger when putting information in comments which may become outdated or wrong without changing it. For example, putting information about what is in other files may be very helpful. However, if the name of the other files or their content changes, then the information in this file becomes wrong. This does not mean that this sort of information should never be used, only that it should be used with care, particularly if the information is at all liable to change, and with the understanding that it must be maintained carefully if it is to retain its original usefulness.
It is a sad fact that many maintainers have been burned by wrong comments so often that they no longer read them; they go directly to trying to understand the actual code. It is up to the writers of new code to restore the confidence of these maintainers by using adequate and clear comments.
4.1.3 Make the comments distinguishable from the code
It is sometimes useful to read just the comments in the code, for example when scanning for code which performs a particular action. Similarly, it is useful to be able to read just the code, ignoring the comments, for example when you want to be certain of what is actually happening. In either case, it is very helpful if code and comments are clearly differentiated, so you can instantly filter out the parts that you do not want to read.
If the comments are packed in densely with the code, then it becomes difficult to perform this separation automatically and you have to carefully watch out for comments and code, 'hand-separating' one from the other.
Clear separation also avoids confusion where a piece of code may be read as a comment, and (more rarely) vice versa:
/* Reset system status flags to null values.
4.1.4 Use character set to characterize comments
The available character set may be used within comments to distinguish the type of comment, or to make it stand out in some way:
/* USE CAPITALS FOR WARNINGS AND IMPORTANT ANNOUNCEMENTS */
The only danger with this is over-use. If every comment is marked in a different way, then they become unusable and unreadable. The solution is to define a limited and useful set.
And the big