misleading comments

Don’t get suckered in by the comments — they can be terribly misleading. Debug only code.

— Dave Storer

Consider a developer named Chuck. To figure out how to use an algorithm, Chuck writes comments to describe each step. A few days later, he fixes a bug in his algorithm, but forgets to change the comments. A few weeks later, another fix is required, resulting in more changes to the code, but the comments remain the same.

A few months later Gary, another developer, is tasked with adding a feature to Chuck’s code. After reading the comments Gary starts adding the new feature and can’t figure out why it doesn’t work.

In an ideal world, comments would always correspond with code, but experience shows that the world is not ideal. If you’re maintaining code and see comments that are no longer correct, by all means fix them, but it’s good advice to only follow the code. Comments are secondary in most developers’ eyes, and when they’re fixing a problem, they test the program, not the comments.

Comments

 (Post a comment) | Comments RSS feed
  1. While this is certainly true, I believe it is still very important to comment the code. For some small things, and to some geniuses, it may not be that big of a deal, but it’s not rare to have some clever code, that no one can figure out. I think this is even more important with Perl and other languages that allow high density code.

    Comment by Cameron on March 18, 2003 @ 8:23 am
  2. Agh, forget the comments and add more code! A whole spaghetti mess of it. :)

    (case
    If this comment = ‘sarcasm’ then ‘laugh’
    Else NULL
    end)

    Comment by Renee on March 19, 2003 @ 9:31 am

Comments are closed