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.10 Summary

• Be clear and concise.
• Ensure comments are correct.
• Make the comments distinguishable from the code.

Heading comments

• Heading comments are multi-line and structured
• Use heading comments at the start of the file, at the start of all functions, and before major data definitions.
• Make the size and detail of the comments match the importance and complexity of the code they describe.
• Define levels of usage of major heading comments, and an appropriate structure for use in each case.
• Use section headers, in capitals (for visibility).
• Use tools to insert/extract information.
• Give an appropriate amount of information.
• Define a small set of standard header templates for all file and function types.
• Describe the internal, external and historical context of the file or function.

Block comments

• Block comments describe the past and the future within the code.
• They may be one-liners, up to five-liners, or bigger. Balance the comment size with the size/complexity of what you are describing.
• Use blank lines to emphasize association of comment with code.
• Put an asterisk at the start of every comment line.
• Use bars above/below to clearly dissociate comments from code.
• Use comment bars across the page to delimit chunks. Use different symbols on the bars to show a hierarchy.
• Decide on a format for each situation.

Trailing comments

• Trailing comments describe one line of code.
• Start the comment in standard column (eg. col 40).
• Decide what to do when code crosses the comment column.
• Put the comment terminator in a standard column too.
• If trailing comments wrap, put a complete comment on each line, and show continuation with ellipsis (..) or indent.
• Define how to comment conditions.
• Comment the end of a long block immediately after the closing brace.

Commenting data

• Comment all data declarations.
• Comment data tables very carefully.
• Comment the declaration to show the intent of its use.
• Give indication of possible values.
• Do not comment out code; use conditional compilation instead.