Your Code Comments should <blink>

There is a huge difference between code documentation and code commenting. Documentation can be super valuable and should be done with a lot of your code. Commenting, the way it is usually done, actually has negative value and should probably be avoided!

What Makes Good Documentation

Good documentation has two common characteristics: it provides clarity, and it’s stable.

Clarity is given by explaining the unit of code at an appropriate level. You are unlikely to need to know the exact algorithm used in a method, but you will need to know how options are used and what the expected outcomes and side effects are. at an appropriate level. You are unlikely to need to know the exact algorithm used in a method, but you will need to know how options are used and what the expected outcomes and side effects are.

Stability matters because the purpose of a method generally doesn’t change over time.

Large document comment blocks solve this need well. Where they most often fail is when they are not kept up-to-date, but being stable, this is less of a concern.

Avoid Comments

Just because comments look like documentation doesn’t mean they serve the same role.

Comments tend to be tidbits and trivialities scattered through your codebase. They fall out of date with reality quickly and usually have little value. My personal rule is this: if I see a comment, it probably means the code needs to be cleaned up until the comment is no longer necessary. If nothing else, there is probably something there that has a wrong name.

Don’t comment it, fix it

The Exception to the Rule

There is one exception to the no-comments rule: leave a comment if the correct code cannot be expressed clearly.

Rarely, a code concept is just surprising or unintuitive. When that is the case a comment may be appropriate, not to explain the code, but reinforce that it may look off, but it is right. The comment is there to draw attention to the code.

Here’s my unpopular opinion: instead of having light grey, quiet comments in your editor theme, make your comments bright red and preferably flashing. This is helpful because it should be rare and you really want to make sure you know that it is there.

Wrapping It Up

In short:

1. Comment less, document more. Comments are a code smell; documentation is a design tool.
2. If something needs explaining, explain it in a stable, structured way—or change the code until it explains itself. Save comments for the weird, surprising edge cases that truly deserve flashing red lights.