Comments on: 3 Misuses of Code Comments

By: Matt Hargus

Matt Hargus — Tue, 14 Jul 2009 21:03:39 +0000

I’ll throw in my two cents and agree with Mark. Nothing drives me nuttier than reading through code that has twice as many lines of comments as code. Well chosen variable and method names can get you a long way in making the logic more understandable. I prefer to comment before the method/function and let the code speak for itself. Good posting, Anthony.

By: Mark Wilden

Mark Wilden — Wed, 01 Jul 2009 21:58:09 +0000

I’ve found that comments are a smell, indicating that the code might need refactoring.

By: Anthony Caliendo

Anthony Caliendo — Wed, 01 Jul 2009 20:20:26 +0000

@Mark Wilden: I agree 100%. When possible, self-documenting code should be used over comments. If the code itself is easier to understand, then you don’t need to worry about the comments.

I think my last example was a little weak and didn’t show my point exactly, but I was trying to focus more on what to do with only the comments and not improve the code quality at all. I think I’ll update my post to highlight that.

By: Mark Wilden

Mark Wilden — Wed, 01 Jul 2009 20:12:14 +0000

I agree with most of this article. My philosophy is that code that’s hard to understand should be commented. But code that’s hard to understand should be avoided.

My main complaint about comments is that they’re not compilable. The comment can be completely wrong, but no test will catch it. So I prefer to express intention in identifier names, where at least there is a compilable correlation between uses.

For example, in the last example, the comment can be avoided simply by putting the affected code in a method called something like map_their_error_codes_to_ours(). By factoring out functionality, the code is easier to understand, even without any comments.

By: Tammer Saleh

Tammer Saleh — Wed, 01 Jul 2009 19:18:21 +0000

I can’t remember where I read it, but the best advice I’ve seen for when and what to comment is to only write comments that include the word “because”. Comments are really only useful for explaining strange application behavior.