Don’t Write Comments in Your Code
When I was starting to code, I often found myself commenting my code as much as I could, trying to describe every detail, fearing that I will forget what the code was for.
Looking at it today, sometimes I found those comments helpful, but in most cases, they confused me more than helped me understand the code.
Some of them were outdated… Some of them unclear… And some documented the code that was wrong in the first place.
So in this article, I will point out some problems with comments in code.
They Become Outdated
As code evolves, comments may not be updated accordingly. This leads to a dangerous disconnect between what the code actually does and what the comments claim it does. Misleading comments like that will just waste your time, and you’re gonna need to either update it or eventually delete it.
The real issue is that comments need to be reviewed with the same scrutiny as the code they’re describing.
Comments That Describe the Code
If you need a comment to describe what the code does, you need to refactor the code.
Your code should be self-explanatory. If you have to add a comment explaining what a function does, then it’s likely the function name is unclear or the code is too convoluted.
Don’t rely on the comments; instead, focus on using clear and descriptive names for variables, functions, and classes.
The proper use of comments is to compensate for our failure to express ourself in code. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration. — Robert C. Martin
So when you find yourself in a position where you need to write a comment, think it through and see whether there isn’t some way to turn the tables and express yourself in code.
The older a comment is, and the farther away it is from the code it describes, the more likely it is to be just plain wrong. The reason is simple. Programmers can’t realistically maintain them.
Commented Out Code
Why is commented-out code so problematic? For starters, it’s often unclear why the code was commented out in the first place. Was it a temporary change? A failed experiment? An intentional removal? Without context, you are only left guessing, wasting your valuable time and energy.
Furthermore, commented-out code can lead to false assumptions and misunderstandings. You may mistakenly believe that the commented-out code is still relevant or functional which could lead to incorrect assumptions and unexpected bugs.
Comments Have Bugs Too
Just as code, comments can contain errors too. They can be typos, incorrect interpretations of the code’s behaviour, or simply outdated information as mentioned before.
When Comments Can Be Necessary
Sure, in some rare cases, comments can be useful.
- Highlighting Potential Issues: Comments can be used to flag areas of code that are error-prone or require further attention. This can be helpful for either you or anyone who may revisit the code later.
- Explaining Regular Expressions: Regular expressions are notoriously difficult to decipher. A brief comment explaining the pattern and its intended purpose can save a lot of time and frustration.
- Marking Incomplete or Experimental Code: Comments can be used to indicate areas of code that are still under development, experimental, or require further testing. This can prevent accidental usage or misinterpretation of unfinished code.
So if you really are writing comments, make sure they say something that the code itself doesn’t.
What do you think about code comments?
