Motley: My code is so readable and self-documenting that comments are unnecessary.
Maven: Comments should address the intent (the why) behind the code, not the how. Extraneous comments around how may indicate refactoring opportunities.
[Context: Maven is doing a code review of Motley’s code and notices there are no comments in it]
Motley: How’s that code review going?
Maven: Not bad. Is there a reason, though, that you don’t have any comments whatsoever?
Motley: Not needed – code comments are for sissies! My code is so readable and self-documenting that they are unnecessary. Just like a natural beauty doesn’t need make-up, my code doesn’t need comments!
Maven: Your code is good, I’ll give you that. However, I can see a few places where comments are necessary.
Motley: I have to assume that the people reading my code are smarter than slugs – and hopefully less annoying. Beings above slugs in the evolutionary chain don’t need comments.
Maven: Score one dig for you! Ouch. There are good practices and bad practices with comments. Let’s start with the bad. If you are commenting code to meet some kind of comments-to-lines-of-code metric, that’s the wrong reason.
Motley: Hahahaha. That’s as ridiculous as your last haircut!
Maven: Don’t laugh – I’ve seen it done. Comments obviously have to add value to the person reading the code. A comment like this one is totally useless:
// increment i
Motley: Oh, come on. What mor-
Maven: Ah! No insults please. I’ve seen that done too. It’s a waste of bits.
Motley: Ok, Mr. Einstein. When is it good to have comments? I’m paid to write code, not stories.
Maven: Comments are extremely valuable in code when they convey useful information that the code itself cannot. For example, the code itself cannot express the intent that the developer had when she first wrote it. The code itself cannot tell you why the code is the way it is. Sure, a good developer can figure out how it works, but the why may not be obvious. Good comments express intent.
Motley: Isn’t that what a design doc is for?
Maven: Good question! Design docs can express overall intent, but for details, why not keep that really close to the code? That way it may even get updated, whereas we often forget to update design docs when we make an intent change.
Motley: Fine. Keep the low-level design documentation with the code, as we talked about.
Maven: You bet. And you can use the XML comments built into C#. You can use that mechanism to document public APIs, which is another good reason for comments. Let’s save the details on how to do that for another conversation.
Motley: I’m not familiar with XML comments in C#, but it sounds geeky enough to peak my interest! Back to what to comment – I was reviewing Mort’s code the other day and he had a ton of comments in there describing how he implemented things. Since I’m not a slug, I can delve into the code and easily figure out what it’s doing without looking at the comments. In addition, there is a high probability of the comments getting out of date. I just went and removed them all. Perhaps you should have this talk with Mort?
Maven: The best way to solidify learning is by teaching, as Dr. Covey says, so I’ll let you have that conversation with him. He’s going to be a little pissed that you removed all his comments though. Just blindly removing comments is not usually the right thing to do. If someone comments a block of code describing the code itself (instead of intention), there is probably a refactoring opportunity. Usually blocks of code like that have some complexity (thus, the comment). If you leverage the refactoring tools we talked about and Extract Method, you can isolate the complexity behind a nice readable method or class. Comments about how often indicate refactoring opportunities.
Motley: Ok, you’re right – Mort’s probably going to be a little upset. I’ll roll back my change and have a talk with him about refactoring opportunities. I’ll also set him straight on commenting why. I don’t often fully agree with you, but this time I’m easier to please since I was expecting you to tell me to comment the crap out of my code. It’s nice to see your advice is not slug-like.
Maven: You think you know me so well, don’t you Mot? Ha! If we go back to agile principles, we want to do the simplest thing possible, always add value, and do just enough. Everything we talked about fits within that mould.
Maven’s Pointer: Steve McConnell talks a lot about comments in his books and web sites. He has a relatively good checklist that lists good commenting techniques that is worthy of reviewing. I don’t agree with all of the checklist (e.g. author’s name and phone number in the listing), but there are indeed some gems.
Maven’s Resources: Code Complete 2nd Edition, by Steve McConnell, Microsoft Press, ISBN: 0735619670, 2004.