Comments are, at best, a necessary evil. If our programming languages were expressive enough we would not need comments very much—perhaps not at all. 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.
Inaccurate comments are far worse than no comments at all. They delude and mislead. Truth can only be found in one place: the code.
Contents
Comments do not make up for bad code
One of the more common motivations for writing comments is bad code. Rather than spend your time writing the comments that explain the mess you’ve made, spend it cleaning that mess.
Explain yourself in code
It takes only a few seconds of thought to explain most of your intent in code. In many cases it’s simply a matter of creating a function that says the same thing as the comment you want to write.
Good comments
Some comments are necessary or beneficial. But the only truly good comment is the comment you found a way not to write.
- Legal comments
For example, copyright and authorship statements at the start of each source file. - Informative comments
For example that the regular expression is intended to match a time and date. Still, it might have been better, and clearer, if this code had been moved to a special class that converted the formats of dates and times. - Explanation of intent
To provide the intent behind a decision. - Clarification
For example to translate the meaning of some obscure argument or return value, in code that you cannot alter, into something that’s readable. - Warning of Consequences
For example @Ignore(“Takes too long to run”) or “not thread safe, so need …” - TODO comments
TODOs are jobs that the programmer thinks should be done, but for some reason can’t do at the moment. It is not an excuse to leave bad code in the system. - Amplification
Used to amplify the importance of something that may otherwise seem inconsequential. - Javadocs in Public APIs
There is nothing quite so helpful and satisfying as a well-described public API.
Bad comments
Most comments fall into this category.
- Mumbling
Plopping in a comment just because you feel you should or because the process requires it, is a hack. Any comment that forces you to look in another module for the meaning of that comment has failed to communicate to you and is not worth the bits it consumes. - Redundant Comments
A comment that is not more informative than the code, does not justify the code, or provide intent or rationale, does not serve any purpose. - Misleading Comments
Sometimes a programmer makes a statement in his comments that isn’t precise enough to be accurate. - Mandated Comments
It is just plain silly to have a rule that says that every function must have a javadoc, or every variable must have a comment. - Journal Comments
Sometimes people add a comment to the start of a module every time they edit it. As source code control systems do it for us, they should be completely removed. - Noise Comments
Noise comments restate the obvious and provide no new information. For example:
“// Default constructor.” - Scary Noise
If Javadocs are written (or pasted) without paying attention, why should readers be expected to profit from them? - Don’t Use a Comment When You Can Use a Function or a Variable
Refactor the code so that the comment could be removed. - Position Markers
There are rare times when it makes sense to gather certain functions together beneath a banner. Use them very sparingly, and only when the benefit is significant. If you overuse banners, they’ll fall into the background noise and be ignored. - Closing Brace Comments
Although this might make sense for long functions with deeply nested structures, it serves only to clutter the kind of small and encapsulated functions that we prefer. So try to shorten your functions instead. - Attributions and Bylines
The source code control system is a better place for remembering who added what. - Commented-Out Code
Others who see that commented-out code won’t have the courage to delete it. They’ll think it is there for a reason and is too important to delete. Source code control systems will remember the code for us. We don’t have to comment it out. Just delete the code. - HTML Comments
HTML makes the comments hard to read in the one place where they should be easy to read – the editor/IDE. If comments are going to be extracted by some tool, then it should be the responsibility of that tool to adorn the comments with appropriate HTML. - Nonlocal Information
Make sure a comment describes the code it appears near. Don’t offer systemwide information in the context of a local comment. - Too Much Information
Don’t put interesting historical discussions or irrelevant descriptions of details into your comments. - Inobvious Connection
The purpose of a comment is to explain code that does not explain itself. It is a pity when a comment needs its own explanation. - Function Headers
A well-chosen name for a small function that does one thing is usually better than a comment header. - Javadocs in Nonpublic Code
As useful as javadocs are for public APIs, they are anathema to code that is not
intended for public consumption.
| Previous: 3 Functions | Up: Contents | Next: 5 Formatting |