Mike Clark on Sweet-Smelling Comments

A recent article from Mike Clark presents some good advice about comments:

  1. Keep It DRY. The “Don’t Repeat Yourself” principle has wider application than the mere avoidance of code duplication. It’s also a mistake to duplicate knowledge about the intent or functionality of a method in the source code’s comments. As Mike notes, “If a comment already describes what the code does, then the comment is redundant and should be removed.” 
  2. Make the Code Speak for Itself. That is, choose meaningful names for classes, methods and variables. If the purpose of a method isn’t fairly obvious from its name, there’s a good chance that it needs a new name. Invest the time and energy that you would have used writing a comment to “deodorize” that code smell, and use it to come up with a more descriptive name instead.
  3. Write a Sweet-Smelling Comment. Use comments to tell why something was done: what purpose a class serves in the system, assumptions made by the code, and so so.

Posted May 19th, 2005 in Software Development.

Comments are closed.