Mike Clark on Sweet-Smelling Comments
A recent article from Mike Clark presents some good advice about comments:
- 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.”
- 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.
- 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.