mgroves

“Comments are not like Schindler’s List. They are not ‘pure good.’ Indeed, comments are, at best, a necessary evil.”

I have gotten into some heated discussion recently about comments, mainly because I agree with the above quote from Clean Code.  It’s possible that my code isn’t expressive enough.  And by possible, I mean very likely.  However, that doesn’t mean I need more comments: it means I need to write better code.  That’s an opinion, but an opinion that’s validated by chapter 4 of Clean Code.

Here are a couple of points that were brought up in defense of commenting, and commenting often:

• Incompetent programmers: i.e. developers who don’t know basic syntax or basic design patterns
• Non-native English speakers: keywords, classes, frameworks, documentation, variable names, etc. have an English bias.

Those aren’t bad arguments, and they come from experience, but here are my responses:

• Incompetence on the part of someone else is not a good enough reason for me to do extra busywork that doesn’t add value.  If a dev is incompetent but willing to learn, comments aren’t the place to teach.  If they are incompetent and unwilling to learn, then they need to go.  If they can’t be removed, then the organization is likely destructive anyway, and no amount of comments is going to mean the difference between a successful project and a failed project.
• English is the language of programming, for better or worse.  And again, if the programmer is trying to improve their English skills, comments are not the place to learn spelling, grammar, etc.  If they’re unwilling to try to improve, see the first bullet point.

The main point of this chapter is: comments do not make up for bad code.  Clear code is better than comments.

However, sometimes comments make total sense.  A colleague of mine recently discovered that JavaScript’s month index is 0-based.  January = 0, February = 1, etc.  This is surprising behavior, and is a perfect place for a comment.