Sundog Expert Paul Bourdeaux

Paul Bourdeaux

Director of Technology

More Posts

“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.

Posted in: Software, Software Development, Software Maintenance