You guessed it…absolutely nothing.

Well at least according to Uncle Bob in his book, Clean Code.

Here are some quotable gems:

“Comments are, at best, a necessary evil”

“The proper use of comments is to compensate for our failure to express ourselves in code.”

“Every time you write a comment , you should grimace and feel the failure of your ability of expression”

If you feel yourself getting all worked up now, it’s probably because you just experienced several flashbacks to times when a quick executive summary could have saved you hours of puzzling your way through long, frustrating jumbles of logic that ended up having nothing to do with the task at hand.

How could anyone possibly object to a comment when it has potential to save so much time for others in the long run? Isn’t it just because they’re lazy or hate documentation with a passion and are trying to rationalize their own personal preferences and\or shortcomings?

While I can certainly imagine situations where this is the case, I agree with Bob Martin that there is an alternative approach that solves the same problem more elegantly.

Consider the following before and after examples:

Before: With Comment

   1: // determine if I am ready for coffee run

   2: if(weather.IsGray && DateTime.Now.TimeOfDay >= new TimeSpan(0,15,30,0) && thermos.IsEmpty && task.isBoring)

   3:     coder.SneakAwayToStarbucks();

After: With Extract Method Refactoring

   1: if(coder.IsReadyForCoffeeRun())

   2:     coder.SneakAwayToStarbucks();

   3: ...

   4:

   5: private bool IsReadyForCoffeeRun()

   6: {

   7:     return weather.IsGray && DateTime.Now.TimeOfDay >= new TimeSpan(0, 15, 30, 0) && thermos.IsEmpty && task.isBoring;

   8: }

The second code sample provides the same executive summary description of the code, but does it in a more concise way thus helping to eliminate unnecessary scrolling, mental processing, and eye movements while trying to understand the code at a high level.

More importantly, it reduces the chance of becoming a victim of the following scenario.

   1: //wait until coffee cool enough to drink. If it takes too long throw tantrum

   2: if (CoffeeIsTooHot())

   3: {

   4:     Wait(maximumPatienceInMinutes);

   5:     if (CoffeeIsTooHot())

   6:         throw new TantrumException();

   7: }

   8:

   9: DrinkBlackNectorOfTheGods();

If you look closely at the code, you’ll notice that the comment doesn’t really describe what’s going on.

Based on the comment alone, I would expect the application to let me drink my coffee as soon as it reaches an appropriate temperature. In reality, the code will make me wait 10 minutes (my maximum patience level in minutes) before it will even test the temperature again.

This would likely cause me to waste time in a debugging session the first time I noticed that my app was still making me wait even though the coffee temperature was well below the acceptable threshold in the database. That would make me cranky indeed.

This particular example might have just been caused by someone not putting enough effort into accurately describing a comment.

However, a more common scenario for code-comment mismatches occurs when a developer changes or refactors some commented code and then simply forgets to update the comment accordingly. It’s the same type of error that frequently occurs any time you have to keep two disparate dual entry systems in sync. It’s the reason we strive so hard to be DRY in all aspects of software development.

Of course, there is still the possibility of a mismatch when we express code intent through method, class, or variable names instead of comments, but it is less likely to go unnoticed because the code and description are now much more tightly coupled.

Even when following this approach there are definitely some times when you’ll still want to fall back on comments, such as when expressing design intent, protecting yourself legally, or providing xml comments for externally exposed public API’s (NOT internal systems).

However, the vast majority of cases can usually be expressed just as effectively in code.

So the next time you catch yourself writing a comment, it’s worth asking yourself if you can achieve the same goal more concisely through a simple refactoring (renaming, extract method, or insert variable).

Disclaimer: No matter how much I agree with this approach, I grudgingly admit that this still falls pretty firmly into the realm of subjectivity. I’ve simply had too many arguments with superb developers who prefer to see a mix of high level comments and detail code all at once rather than being forced to go to different methods to see detailed implementation. Nevertheless, I can assure you that my subjective opinion on this subject is clearly the right one…:-)

Popularity: 2% [?]