Outdated Comments are better than no Comments

While investigating our locking infrastructure a few days ago I ran across an odd comment.  I was looking at a particular usage of a lock and the comment said that "Using lock type X because we must pump messages here."  Contrarily the lock type being used most definitely did not allow message pumping. 

After a quick history search on the code base I was able to track down the developer responsible for the discrepancy.  He merely forgot to update the comment when making the change.  However he was able to explain the history behind the comment and the switching of the locking type. 

I’ve heard people argue in the past that they didn’t comment code because comments get out of date and lead developers in the wrong direction.  They might do it correctly but they didn’t trust the next guy.  Then the comment would be wrong and useless for the next developer.

I think this is a example of why that mentality is wrong.

  1. Even though it was currently wrong it was historically accurate
  2. The commented add good insight into the choice of locking mechanism
  3. It added a bit of detail into the historical architecture of the code base.
  4. It was a heck of a lot better than staring at a comment-less field that appeared to exist for no reason.

I’m not arguing that comments which are flat out wrong at the time they are authored are a valuable resource.  Yet not commenting because you don’t "trust" the next guy is equally wrong.

Comments (4)

  1. "However he was able to explain the history behind the comment and the switching of the locking type."

    If you had to track him down, you didn’t achieve anything by having a wrong comment. svn blame would’ve achieved exactly the same result?

  2. Mike says:

    Yeah, your logic is flawed.

    In the event that you have a comment that is wrong but in a subtle way so as to introduce an incorrect assumption on the part of the reader is monumentally bad.

    Its likely that they’ll then sit there an hour scratching their head as to WTF you are on about. Been there, done that. The original author isn’t always around to ask in the event of an open source project or in a company with a high developer churn rate.

    If you want history, use version control.

  3. Sebastien,

    The problem is without the comment, the line itself would be completely uninteresting.  It was just another lock that needed to be converted with no history.  I wouldn’t have immediately thought of it as a blame point.  

  4. Mike,

    Without the comment though you are essentially staring into a vacuum.  Source control is a great history tool but doing source control search for every variable, expression, etc … is far too time consuming to be useful when I just need a little bit of quick info.  

    I agree a bit of head scratching will occur.  But I’d also argue that it would happen in the abscence of the comment.  What the comment gained me was 1) immediately finding out that particular piece of code was fishy and 2) a historical view into how the code got into that state.  

    I agree once you have #1 then #2 can usually be accomplished with source control.