Comments in code are like traffic signs. If they’re not there at all, chaos ensues because no one knows how anything is supposed to work. At the same time, having too many of them–or having ones that are too complicated to read quickly–also leads to chaos, because no one can digest the information they are intended to convey. That’s a long way of saying that there is a right way and a wrong way to perform code commenting in source code. To help demonstrate what not to do, this article offers five examples of code commenting practices to avoid.
1. Don’t comment on the obvious (but think carefully about what is obvious).
Perhaps the most basic rule for writing good comments in source code is to avoid commenting on the obvious.
Newer programmers in particular have a tendency to feel like they need to write a comment to explain what every function–or sometimes even every line of code–does. That may be a good practice if you’re learning coding and want to force yourself to think through the purpose of the code you write. However, once you’ve progressed beyond that stage, commenting on the obvious leads to too many comments for anyone to use effectively. If you comment on everything, another programmer working with your code won’t know which comments are actually worth reading.
The caveat to this rule is that what seems obvious to one programmer may not be obvious to others. It’s important not to go to the opposite extreme and comment on almost nothing because you assume that if something is obvious to you, it must be obvious to everyone else. This perspective is, in a way, a form of imposter syndrome.
As a general rule for determining what is obvious and what is not, consider whether the code you’re writing follows widely used conventions and syntax. If it does, it probably doesn’t need a comment. Everyone does indeed know what i++ means. On the other hand, if you are using obscure operators, formatting your code in unusual ways for some reason or using a library that few other programmers are likely to know, comments can help increase readability.
2. Don’t use comments as an excuse for unclean code.
It can be tempting, when you’re in a rush, to churn out poorly written code, then write a comment that explains what it actually does or why you took the shortcuts that you did.
This might be OK as a temporary fix, but don’t make it standard practice. Instead, strive to make your code itself as clean and readable as possible. This keeps the need for comments minimal in the first place.
3. Don’t use comments to replace documentation.
Developers may not enjoy writing comments, but they tend to despise writing documentation even more. For that reason, it’s not uncommon to see programmers attempt to leverage comments in lieu of documentation. They use comments to document features, give usage recommendations, explain how to build the code, and so on.
This is not what comments are for. The typical inline comment explains how a small and discrete piece of code works, or gives developers the information they need to modify or expand on that specific segment of code.
Sometimes, comments (specifically, header comments) are used to describe the overall purpose of a source code file, but, even there, the information should be concise and to the point.
Information that relates to things that are extraneous or tangential to the actual contents of the code, such as how to build and deploy an application, should be stored in a documentation database, not in source code comments.
4. Don’t note authorship in code comments.
This recommendation is debatable to an extent. But, in general, I’d contend that using comments to give yourself credit as the author of a particular snippet of code is poor practice. This is especially true given today’s version control systems, which can typically be used to trace code authorship on a granular basis without having to look at the source code itself.
If you write a large chunk of code and want to note yourself as the author in a header comment, that may be OK, especially if your role won’t be recorded in version control. But noting authorship of specific chunks of code in inline comments is usually a bad idea.
So is using comments to record other metadata, such as when the code was originally written or last modified. That information can also be pulled from version control systems by anyone who needs to know.
5. Don’t write comments that refer to other comments.
Finally, comments should be short, sweet and self-contained. They’re not documentation files, where one page of documentation might link or refer to another.
For that reason, comments that say things like “same issue as with my_func(); see above” are not very effective. If a programmer has to scan up and down your source code file just to figure out what a comment means, the comment should be clearer, or should not exist in the first place.
Conclusion
Perhaps the overarching theme of the code commenting best practices described above is that the fewer comments you have, the better off you probably are. Don’t comment on the obvious, don’t write comments when you should be writing documentation, don’t use comments to record metadata, and don’t write code that is so unclear that it requires lots of comments. Follow these guidelines, and you’ll not only write better comments, but also better code.
