Ever since the beginning of my journey to become a solid programmer, it was taught to me that commenting code was always a good thing. You can never have enough comments, they would say. The golden rule was to have at least an equal comments to code line ratio.
All of this made sense to me back in college. Nothing wrong with being too descriptive right? Wrong! Sure, comments can be a great thing. There’s nothing better than reading a comment that helps you understand some complex piece of code. However, after working in the industry for awhile, I’ve seen the dark side of comments.
The other day, while working on one of many bugfixes, I came across an obfuscated piece of code. Instead of diving into it and figuring out where each function/variable/whatever came from, I trusted a couple lines of comments above the code. Thank god for comments, right! Wrong again! Apparently, whoever wrote that code wrote it over someone else’s code, but hadn’t updated the comment because he hadn’t noticed it. So the comment was downright false. A lie. Imagine dealing with that all day. Ever try to understand thousands of lines of code where some comments are leading you down the wrong path, like satan?
My thinking is, keep the comments to a minimum. Instead of commenting excessively, try to write your code in such a way that it doesn’t *need* too many comments to understand. Good code speaks for itself 
And don’t be lazy, always update the comments as needed as your code changes. If you come across a useless one, throw it out… like a leper!
Because I’ve been getting some weird feedback on this post (my fault most likely, for being a professional programmer and not a writer), let me reiterate my point here…comments, when used appropriately, are a good thing! The key word is appropriately. Don’t diarrhea all over your code. It’s stinky. And too many people do it. When a developer sees a piece of code, he tries to understand. When he reads a comment, he is inclined to believe it right off the bat. So don’t mess with his head. Get it?
Oh and hey, leave some “comments” below if you’ve had bad experiences too
9:14 am, August 4, 2008Mike /
Based on your example, why not tell everyone not to comment their code at all. The same thing could happen with a minimal amount of comments as with lots of comments. What do coders who work on the same code base as you think of this? I hope no one takes this advice.
10:14 am, August 4, 2008proc /
Mike:
True, even with a minimal amount of comments, my situation might not have been avoided. But slathering a lot of comments on poorly written code does greatly increase the chances, doesn’t it?
Like the reason why shooting buffalo was so easy 100 years ago.
As for my fellow coders…about 60% of our codebase is written in Python, which is generally a pretty clear, concise language. With that said, much of the time it’s very easy to follow the code. Our top programmer here is actually the guy that brought this “comments” issue up with me many times, so we’re all pretty much in agreement.
Maybe its because we work with a straight-forward language like Python, I don’t know…but it’s the same for every language – people assume comments “don’t count” because they don’t do anything – nope! They should be treated as lines of code themselves, they are just as important, and must also be maintained.
5:52 pm, August 4, 2008nasir /
I think commenting, as with programming itself is almost an art form.
There are obviously many different styles of writing comments, large blocks at the beginning of the function, inline comments, the pre/post conditions, etc.
For legacy systems, often comments are the only thing you have to go by, especially with no experts or people familiar with the code available to you. As such, I must agree that outdated/inappropriate commenting can often be worse than too little commenting. What makes sense to the original programmer can easily be overlooked or skipped by people who maintain the code later on. Small quick bug fixes with no documentation to the changes start piling up and everything gets changed.
I recently ran into this issue myself where I had to update some code that hadn’t been modified in about 5 years and the original author was gone. There were so many small changes, the comment block above the function referenced calls that were obsoleted.
I think good commenting will come with practice as you get exposed to more of other people’s code and comments, just like good coding skills.
6:42 am, March 3, 2009mtness /
This reminds me of a good word:
“code/comments are like sex:
if it is good, it is really, really good.
if it is bad, well, it is still better than nothing at all.”
Kind regards from Germany,
mtness
5:38 pm, March 3, 2009proc /
@mtness
I dunno, I’ve been to prison before and that kinda sex is the kind I can definitely live without =( Thanks though!
4:50 am, April 28, 2009mtness /
Hi there again, proc!
I didn’t want to offend you in any way –
the saying might only relate to the “standard geek” definition of the word
Of course, really good code always speaks for itself.
“Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.” Antoine de Saint-Exupery
Kind regards,
mtness