During our daily standup the other day, one of the developers was complaining about the lack of commenting in a module that was written by a 3rd party consulting firm.  This got many frustrated nods from the other developers in the group, which in turn led to a discussion of comments overall in our code.  There seemed to be a general consensus among the group that the commenting in our code needed to be improved overall.

The reason I found it interesting (and by interesting I mean to me only) was the the timing of it all. 

I’ve been on a kick lately to read nothing but Agile books (instead of the usual books on specific languages or technologies).  The one currently occupying my bedside table is a book by Robert C. Martin (aka “Uncle Bob”) called Clean Code : An Handbook of Agile Software Craftsmanship. 

Literally only a day or two before this particular stand-up meeting, I had read the section on commenting in the book.  In fact, Uncle Bob’s views on the subject were so strong that he dedicated an entire chapter to it.  He argues that comments overall are a “necessary evil” and are only needed as a means “to compensate for our failure to express ourself in code.”  He hopes someday that languages evolve to DSLs that are self-documenting.

He reasons that comments are bad because Agile code changes over time.  Oftentimes, the comments don’t get maintained along with the code.  So the more code gets changed, the comments become further away from the current intent of that code.  In fact, he boldly states that comments lie (though not necessarily intentionally), and that inaccurate comments do more harm than no comments at all.  A bad comment is worse than no comment (maybe Uncle Bob was a lawyer in a former life?). 

Well, if that’s the case, why bother commenting at all?

He does give some examples of useful comments:

• Legal comments, such as copyright headers, author statements, or ownership rights
• Warning of consequences
• TODO comments, which can be caught in IDEs as warnings

On the other hand, he provides numerous examples of bad comments:

• Documenting a “hack”
• Comments that mirror the functionality and/or naming of the code piece it describes
• Poorly written comments, which can be harder to read than the code itself
• Journal comments that log each time the code is changed
• Noisy comments that provide no value (e.g. // ignore )
• Position markers (e.g. //////// Public Methods /////////////)
• Closing brace comments (e.g. // end while)
• Commented out refactored code (a personal pet peeve of mine)

I don’t know if I agree with the extremist approach of removing all comments from my code.  But I do agree that comments are often abused as a replacement for good code.  The rule of thumb I came away from the book is: if you feel the need to document a complex chunk of code with a comment, that is a sure-fire sign of a code smell.  Step back and look at the code from an maintenance perspective.  Is this code likely to change?  What are the odds the comments will change with it?  Is the comment articulating my intent well?  Have I named my variables/methods/classes intuitively?  Most importantly - can I refactor the code into a standalone method that can be named expressively?

Comments can be useful, but many times end up being the poor man’s excuse for lazy coding.  Don’t be that guy (or gal).  Strive to make your code readable without having to resort to comments.

Friday, October 17, 2008 8:54:34 PM (Eastern Standard Time, UTC-05:00)      Comments [0]  Agile | Back To Basics | Programming