“Perfectly Understandable” Code Still Needs Comments

Recently, Jeff Atwood of Coding Horror attacked the idea of over commenting code. In his blog, he asserts that “Junior developers rely on comments to tell the story when they should be relying on the code to tell the story.” I actually agree with this statement, but one should be wary of trying to make the code tell the whole story. Often times, code that is perfectly understandable to you may not be to somebody else.

Jeff goes on to say ”...if you feel your code is too complex to understand without comments, your code is probably just bad. Rewrite it until it doesn’t need comments any more.” But at what point does the code no longer need comments?  As the developer, of course it makes sense to me.  But what about the next person that comes along? We have all heard Kathy Sierra and Bert Bates’ famous line - “Code as if the next guy to maintain your code is a homicidal maniac who knows where you live.”  I would rather put a line or two of comments in to ensure that I don’t send the next person into a killing rage.

Jeff’s example is dissected by Dan Dyer in No, Your Code Is Not So Great That It Doesn’t Need Comments.  In this blog, Dan correctly points out that even code you think is “perfectly understandable” may not be.

Sam Larbi takes his anti-comment stance to an even more stringent level.

Besides, you’re a programmer, you ought not have trouble reading programs. If you do, it’s likely you haven’t made it simple enough, and what you really think is that the code is too complex to understand without comments.

I disagree. I like to think of myself as a fairly competent programmer, yet sometimes even well written code can take a little while to wrap my head around (again, see Jeff’s example).  Also, sometimes the code is easy enough to read, but the reason why it was written that way may not be as apparent.

In my humble opinion, encouraging developers to avoid comments is a poor solution. If given the choice between excessive comments and no comments, I would choose excessive. Ideally however, we can find a happy medium between the two.


Returning visitor? Please login or register.

Hi Paul - It doesn’t sound like we’re in too much disagreement on the issue of commenting the “why” as opposed to the “how”.

A couple of points I wanted to make:

You said “I would rather put a line or two of comments in to ensure that I don’t send the next person in to a killing rage.”

What if that person was going to go into a killing rage /because you littered your code with comments/?

Comments should not just be tossed around - instead, like your code, you should /really/ think about it and have a /good/ reason for including it.

Regards, and thanks for the link love. =)
I also wanted to clarify my position a bit: I’m not anti-comments. I’m anti-crap-comments that don’t need to be there. I think that most comments I see (and writemyself), where the comment /appears/ justified, are just crutches for crappy code.

I’m advocating taking a look at your code and trying to make it better as opposed to throwing in a comment to try to make it understandable. If, after some consideration you feel a comment is justified, then feel free to add it.

But people seem to think because comments aren’t executed they doesn’t require as much thought as the code.

I think they should be considered as important as the code - and a comment that isn’t there is as good as code that isn’t there, assuming everything still works like it’s supposed to.

Sammy Larbi Posted on: Aug 08, 2008 at 09:32 AM

Thanks for the reply Sammy.  I think your line “I’m not anti-comments. I’m anti-crap-comments that don’t need to be there.” is absolutely correct (and made me laugh).  Thank you for clarifying your position and I hope I did not misrepresent it.

Paul Bourdeaux Posted on: Aug 08, 2008 at 10:53 AM

Leave A Comment

Please help us stop spam by answering the question below: