Comments Are Always Failures

By | January 22, 2011

The title of this post comes from Robert C. Martin’s Clean Code, which embarrassingly enough I have yet to read. I stumbled across this as I was formulating my thoughts for this post, which had been percolating for a while. I was looking for a snappy title which summed up what I believed, and “comments are always failures” does it perfectly.

There is really not much to say here. I’ve challenged the notion myself, as I’m not a believer in generalizations. But in every case I can recall in my team’s recent work, a comment was indicative of simply not having enough time to do things right. For example:

  • “Since we don’t have that database in our development environment, just comment that test out so we can have it for reference when we do need to run that test.”
  • “Those data-dependent tests are failing because some data changed (go figure), just comment them out until we have enough time to go back and fix them.
  • “So the business wants us to do something with this object that is counter to what the object name means? Go ahead, implement the change, and then add a comment so we remember what we did 3 months from now.”
  • “Oh look, a comment that says ‘need to do this better.’”

And then there are the myriad other comments that add no worth, e.g. a comment that says “Applies taxes to purchase amount” on a method called “ApplyTaxesToPurchaseAmount.” In every case, had we had the time, we would have been better off removing the comments and making our code more intentful. Comments are a crutch that allow us, in our lazy moments, to accept less-then-perfect object names, method names, and class hierarchies, all because we have a comment nearby that really explains what we meant. Garbage.

Comments are always failures. As developers, we need to drill this into our heads and make it a mantra. We need to augment our automated builds such that instead of warning us if we don’t have at least X% comments, it fails the build if we have above X% of our code as comments. Instead of having to subtly switch gears in my head during a code review when I come across your comments so I can read and understand your prose, I should immediately ask “what happened here that we had to add a comment?”

Comments are always failures. I challenge anyone to prove this wrong.