In the chapter on commenting, McConnell divides comments into six categories. Figure 3.1 gives summarized versions of his definitions, with some of his commentary.
- Repeat of the code: States what the code does in different words. Just more to read.
- Explanation of the code: Explains complicated, tricky, or sensitive code. Make the code clearer instead.
- Marker in the code: Identifies unfinished work. Not intended to be left in the completed code.
- Summary of the code: Distills a block of code into one or two sentences. Such comments are useful for quick scanning.
- Description of the code’s intent: Explains the purpose of a section of code, more at the level of the problem than at the level of the solution.
- Information that cannot possibly be expressed by the code itself : Copyright notices, confidentiality notices, pointers to external documentation, etc.