March 10, 2020
Comments are sometimes used to explain the thoughts that can’t be explained with code. Other times, they’re used to explain what some messy code is doing.
In this article, we’ll look at how to write comments that are useful and don’t clutter up the code.
Do We Need Comments?
Most code should be self-explanatory. If it’s not, maybe we should think of a way to make it so. There are probably ways to make code clear enough so that comments aren’t needed.
Comments get outdated quickly as code changes since they’re often neglected when code changes. They aren’t updated as frequently as the code. This means that the code will deviate from the original code that it describes.
Code also moves around a lot. The comments don’t follow it.
We can update the comments as frequently as the code, but it’s probably better to make the code clear enough so that we don’t need the comments. The code is what we need to deal with in the first place. The comments are just there to support the code.
Inaccurate comments mislead the people who read the code. That’s not good since it leads to a wrong understanding of the code and bad changes can be made from it.
Comments Can’t Make Up for Bad Code
Comments may make some people more comfortable with writing bad code since they think they can make up for the mess with comments.
Clear code is much better than having messy code and lots of comments. The time writing comments is better spent on cleaning up the mess.
Let the Code Explain Itself
We can easily write code that explains itself. For example, instead of writing: