Three Rules for Code Comments

Code comments are a topic which still draws a lot of heat (and an occasional burst of light) in programmer debates.

I understand.  If you are dealing with long, complicated functions with dozens of if conditions, many levels of indentation, and a number of design issues all at once then comments are a survival mechanism. They're absolutely an indispensable coping mechanism. Deleting them will make your code many times worse than it is already. In this regard, comments are a lot like the single-exit rule.

Also, like the single-exit rule, this coping mechanism is unnecessary when code is small and simple and everything is reasonably well-named.

Still, we find many comments that code would be better off without.

After spending time in debate, discussion, observation, and consolidation, my friends and I have come to the realization that there are only three important rules governing the use of comments.


The Primary Rule:

Comments are for ideas cannot be expressed in code. 

The Redundancy Rule:

Comments which repeat the code (add no information) must be deleted.

The Single Truth Rule:

If the comment says something that the code could say (via explanatory variables, functions, or even by better naming of existing entities) then the code must be changed to make the comment redundant (see rule 2). 

If we believe a comment is necessary, we examine it in the context of the code. Can we apply the Single Truth Rule to make the comment redundant (often via "extract method" refactoring or possibly with some renaming)? If so, then we invoke the Redundancy Rule and drop the comment.

Sometimes, we find that the Primary Rule is in effect. Perhaps we were forced by constraints to make an unusual choice (such as bubble-sort instead of quicksort, or an exhaustive sequential search instead of a binary search) and the code cannot express that algorithm choice easily. In that case the comment can remain. At some point, someone may come along and use refactoring techniques (perhaps renaming bubble_sort to slow_sort_in_constrained_memory).

This set of rules is also present with some good commentary at the Ruthlessly Helpful Blog and is included in the Code Smells album at Industrial Logic.