Types of code commenting

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.