Next: What should comments Up: No Title Previous: Size and complexity

Comments

Most programming languages have a facility for adding informal text to the source text of programs: comments. Comments have an obvious role in aiding the reader of a program (even the most mnemonic identifiers cannot tell the whole story). Effective commenting requires long practice, and a good feel for the kind of detail that the reader needs.

It is not appropriate to use a vast amount of comment text; that can be as bad as none at all. The intelligent reader needs signposts and hints - not impenetrable detail, nor a wilderness.

One important point before discussing commenting style in detail:

5inComments are not something to be added to a program when it is about to be ``delivered'' - it is easier to include them in a program as you type it in, and then they will also be of assistance to you.

This principle applies equally to program layout and choice of identifiers, although it seems more natural for programmers to deal with these from the start.



Simon Jones (sbj@cs.stir.ac.uk)