Wednesday, March 11, 2009

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.


  1. I like that, very simple, concise and full of experience.

  2. I totally agree with these rules

    In fact, I haven't thought of the second rule before, and may be one day I develop an add-in to ignore comments when you copy and paste the code (if no one else do/did before)

    I wanted also to share my comments about comments

  3. 1: Personally I would rather read 1/2 a sentence telling me what the next ten lines of code are doing as opposed to reading the 10 lines of code but hey I'm lazy. I think there is a balance between your world and the over-commenter.

    2: If you copy and paste code, you have stuffed up. So making rules on stuffing up sounds a bit silly to me.

  4. Anony - cut-n-paste is evil, but cut-n-paste with comments intact is nuts.

    I would rather see:

    # blah

    replaced with:

    blah() # in original place

    # In other place...
    def blah():

    So I read whatever the comment used to say as the name of a function.

    Besides, comments lie. You can't afford to not read the code because te comment is there.

    Also see my better explanation at
    Agile In A Flash.