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
The Dark Side of Code Commenting
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