Comments — Breaking Down Clean Code Ideas

This article is part of the “Breaking Down Clean Code Ideas” series in which I will go chapter by chapter and section by section, extracting the ideas of the authors of Clean Code in a few sentences or paragraphs.

If you did not see the previous chapter, I invite you to read it by clicking here Functions.

Chapter 4 - Comments

Comments are not “pure good”. Indeed, comments are, at best, a necessary evil. The proper use of comments is to compensate for our failure to express ourself in code. Comments are always failures.

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.

Comments lie. Not always, and not intentionally, but too often. 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.

Truth can only be found in one place: the code. Only the code can truly tell you what it does. It is the only source of truly accurate information.

Comments Do Not Make Up for Bad Code

• Spend time writing good code than writing comments to explain it.

Explain Yourself in Code

• Comments are a poor vehicle of explanation; instead, write code that explains its intention.

Good Comments

• The only truly good comment is the comment you found a way not to write.
• Legal comments, copyright and authorship statements are necessary and reasonable things to put into a comment at the start of each source file.
• You can add informative comments to the code, as long as there is no other absolute way to explain the code using function and variable names.
• Some comments are useful when they’re used to explain the intent; in other words, to clarify why the author of the code made that decision some time ago.
• Sometimes, adding clarification comments to translate a meaning into something readable is helpful. However, on the flip side, it makes it difficult to verify whether they are correct

Clarification comments

• Comments that warn of consequences are sometimes really helpful.
• “To do” comments are jobs that the programmer thinks should be done, but for some reason can’t do at the moment. It might be a reminder to delete a deprecated feature or a plea for someone else to look at a problem. Whatever else a TODO might be, it is not an excuse to leave bad code in the system.
• There are some special cases where a comment may be used to amplify the importance of something that may otherwise seem inconsequential. Notice the “special cases”.
• Javadocs in public APIs are quite so helpful and satisfying as a well-described public API. But keep in mind they are comments as well and they can lie. This only applies to public APIs, not the internal ones.

Bad Comments

• 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 do not serve. If the comment does not add useful extra information, why use it?
• Misleading comments can lead to misinformation and confusion. If you write a comment, try to be as accurate as possible. Misleading comments can make you waste a lot of time debugging because they told you lies.
• 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. This is no longer necessary now that we have source code control systems.
• Noise Comments. Sometimes you see comments that are nothing but noise. They restate the obvious and provide no new information.
• Don’t use a comment when you can use a function or a variable.
• Closing Brace Comments. Sometimes programmers will put special comments on closing braces on long functions, instead try to shorten your functions.
• Attributions and bylines comments, used to remember who added a code, are no longer needed with source code control systems.
• It’s a bad practice to comment-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.
• Don’t write comments on places where they don’t belong to. Comments are near the local context. Don’t write descriptions about outside the current context.
• Don’t write comments with too much information. As the adverb indicates, ‘too’ often carries a negative connotation.
• Don’t write comments that have no connection with the code they describe. This may seem obvious, but some people don’t understand.