//FIXME -- Jason Felice’s blog

It’s been a little while since I wrote Comments Unhelpful, and two recent events bring me back to the topic. The first event is discussion brought up by a colleague about implementing commenting requirements in our coding standard. The second event is Mark Schumann’s recent post including explanation of what would have helped him crack the codes of a physicist.

Since I’ve ranted about what doesn’t work, perhaps I should post what I’ve found that does work.

Rule One: Prefer “Rename Class,” Rename Method, and Extract Method Over Comments

The code itself is durable. Comments are not. If you can obsolete the need for a comment by renaming a class or method, do it.

A note on Extract Method. If you haven’t read Fowler’s Refactoring, this was a particularly enlightening “Aha!” for me.

When you are writing a function, and those little one-line comments come up that explain the next little logical block of code, you should extract that little block of code into a method, name it so that it conveys the information from the comment, and kill the comment. This is good design as well as good documentation.

Rule Two: Don’t Put Anything in a Comment which has Already Been Expressed

This simply means that you should apply DRY to comments like you would apply it to any other piece of the system. Many of my points in Comments Unhelpful are directly related to this rule.

Do not include any part of your function or class signature, such as return type, parameter types, exception names – and certainly don’t repeat the function or class’s name. The only exception is referring to an item to add more documentation. Also, do not feel compelled to add documentation for every parameter if you have no non-obvious information to add.

Do not include any information available from version control, such as author, modification date, or revision number. Version control is much better at tracking this information than you are.

Rule Three: Class and Method Comments Should Contain a One-Sentence Summary

This is not an argument for adding a comment to every method and class, but every method and class which has a comment should start with a one-sentence summary. This enables programmers to understand the code more quickly, as well as supports tools like Javadoc and Doxygen.

The one-sentence summary should clearly document the item’s single responsibility. I can’t find reference to it now for proper attribution, but I once read that every class in the system should be describable in one sentence, and the sentence should always be simple (as opposed to compound) and have no qualifying clauses. This works to expose design problems with new and refactored code. You may not be able to apply this if you are documenting existing code without refactoring.

Use first-person active voice to help clarify your thoughts. For example, “I sort a list into an order suitable for presentation.” instead of “Sort a list for presentation” or “Sorts a list for presentation” or “This method sorts a list for presentation.” This is a sort of a commenting-by-rote jamming mechanism. I don’t know why, but personifying classes and methods seems to reify them better. I first encountered this in emacs lisp code.

Rule Four: Synopsis Over Exposition

“Synopsis” is the contribution of perldoc to my commenting rules. Exposition is hard to write, hard to read, and harder to maintain. A short synopsis of how the class or method is intended to be used is much easier to read and understand. You can add comments to your synopsis to clarify non-obvious points. You also receive the additional benefit that when you rename a method or class with a text search-and-replace, it does not invalidate your synopsis.

For example:

/**
 * I manage a pool of devices.
 *
 * Synopsis:
 *   DeviceContainer* p = new DeviceContainer();
 *   p->AddDevice("COM1:");
 *   p->AddDevice("COM2:");
 *   if (!p->Check()) fail("Don't have all devices!");    
 */
class DeviceContainer {

Rule Five: Why, What, and Not How

This is the “Linus Torvalds” rule. From the Linux kernel CodingStyle document:

Comments are good, but there is also a danger of over-commenting. NEVER try to explain HOW your code works in a comment: it’s much better to write the code so that the _working_ is obvious, and it’s a waste of time to explain badly written code.

Generally, you want your comments to tell WHAT your code does, not HOW. Also, try to avoid putting comments inside a function body: if the function is so complex that you need to separately comment parts of it, you should probably go back to chapter 6 for a while. You can make small comments to note or warn about something particularly clever (or ugly), but try to avoid excess. Instead, put the comments at the head of the function, telling people what it does, and possibly WHY it does it.

Rule Six: Astonishment

Anything which would astonish a programmer attempting to use the entity should be documented if it can’t be corrected.