The Six main types of comments are

---

• Trivial comments, Comments that just repeat the code, line for line, this type of comment should always be avoided

      // Increment employeeCount by one
      employeeCount++;

• Explainatory comments, typically used to explain complicated, tricky or sensitive pieces of code. If the code is so complicated that it needs to be explained, it's almost always better to refactor / improve the code than it is to add more comments. Make the code itself clear and then use brief summary or intent comments instead.

• Marker comments, a note to one's self to come back and do some work that isn't finished yet. This is a useful form of comment during development, only if your final shipping code has been cleaned up and all comments of this form have been removed and replaced by correct functionality. This type of comment should be standardized by all developers on the team, so that is easily found and understood and a post-process tool could be written to scan the source code looking for left-over comments of this type and flag them as bugs.

     bool MyCoolRoutine( ... ) {
        // BUGBUG - needs to be implemented...
        return false;
     }

• Summary comments, a comment that summarizes multiple lines of code into one or two sentences, this form of comment is useful, especially for people trying to maintain the code after the original developer has moved on.

• Intent comments, a brief comment that explains the original intent behind a section of code or a routine. Intent comments are meant to operate more at the level of the problem space than at the level of the actual implemented solution. These types of comments are also useful for helping to understand the code and the decisions behind the code.

• Meta-Information comments, comments that capture information that simply can't be expressed in a programming language directly. This would include copyright notices, confidentiality notices, version numbers, housekeeping details, notes about the code's design, references to requirement's or architecture documentation, URL's to online documentation that explain the algorithm(s) being implemented, optimization notes, comments required by documentation tools, bug fixes, etc. This type of comment is always acceptable but should be clearly differentiated from the rest of the code. These type of comments should typically be put in the File, Class Interface, or Routine block comment headers.

-- ShawnDB - 16 Jun 2008
to top