Some comments can be useful given certain circumstances. However, they have a tendency to pollute our codebases. They become less accurate and more misconstrued over time. On the contrary, they can give developers very useful context in a pinch. Regardless, they too often serve as a justification for writing poor quality, and unreadable code.
Partially acceptable comments (sometimes… kind of….)
-
Informative comments: can be useful for supplying basic information, but are often avoidable by using better method names or extracting certain responsibilities to a class.
-
Explanation of Intent: sometimes our implementations of certain functionality can be somewhat unclear and hacky. Ideally we’d take the time to refactor our code so that it is more intuitive, but when time isn’t a luxury that we have, it may be better to leave a comment that explains our intention.
-
Clarification: it can be useful to translate the meaning of an obscure variable or return type into something readable- again, it’s better to find a way to make the argument clear without a comment, but this can be an acceptable approach when working with some sort of library, or code that you cannot change for whatever reason.
-
Warning of consequences: developers can sometimes appreciate a comment that warns them about some sort of expensive process or third party call that may take a substantial amount of time, or computational power. Unclear side effects should always be avoided in our code, but if they slip through for whatever reason, it can be nice to let people know.
-
TODOS: TODO comments are too often used as an excuse to leave poor code in the systems we build. The only acceptable time to use one, is a case where something is blocking the thing that is to be done, and therefore can serve as a somewhat useful reminder.
The bottom line: The only truly good comment is the one that you found a way not to write.
The types of comments listed above can be justified given certain situations. The following types, and many others, are never justified.
Completely unacceptable comments
-
Misleading: Comments that are misleading are the worst of all. If a comment insinuates that the code is doing one thing, but it actually does something else, than it is doing the reader a disservice and they would be better off just reading the code. This tends to happen over time, as code changes, and comments don’t. This is why it is crucial to not just look at comments, but also look at the code and verify that we understand what is actually happening.
-
Redundant: Comments that reiterate what the code already says are a complete waste of time. They break the flow of the programs, and make developers do a double take for no reason.
-
Journal comments: these are comments of changes to our code over time. They used to be useful before we had git. Now- they’re just wasted bits.
-
Closing brace comments: if your program has such complex nested blocks that you feel the need to add comments that clarify which closing brace is closing which opening brace- you’ve got much bigger problems. This is a very clear indication that the code needs to be refactored.