Skip To Content
Clean Code

Comments

At best comments are a necessary evil. Only use them to compensate when you fail to express yourself properly in code - this means comments are a sign of failure, so be sure they're the only option left.

Comments are bad because the longer they're not maintained, the more they become lies. And it's not realistic to maintain them as needed while the codebase changes. Inaccurate comments are worse than no comments since they mislead. The only reliable source of truth is the code itself.

If you write comments that make up for bad code, delete the comment and improve the code. This can be as simple as

Good Comments #

While the best comments need not be written, some comments are indeed necessary. At least until you find a way to remove them later.

Some comments are required for legal reasons, like copyright messages. Some IDEs can automatically collapse these comments to avoid clutter. It's also best to refer to external documents when you can instead of pasting the whole text in the code.

Informative Comments #

Comments explaining a function's return value can be useful, but only when it can't be explained with the function's name. But when its complexity can't be expressed in just a name, like telling how a regular expression works, a comment can explain why. But abstracting that regex away would be even better.

Other informative comments include

TODO Comments #

TODO comments use that specific four-letter word and mark jobs that should be done but can't be done at the time. Leaving them there at all is bad enough, so make it a habit of finding and removing them whenever you can.

Bad Comments #

Most comments are like this, and unlike good comments, have no reason to be there. Remove them as soon as possible. Some basic examples of bad comments are: