The Real Power of Comments

// I HATE COMMENTS
# I HATE COMMENTS
<!-- I HATE COMMENTS -->

Recognize this attitude?

It is easy to understand why developers dislike comments. When comments are forced by coding standards, idiot managers, or teammates who demand documentation for everything, the result is usually meaningless noise.

But comments are actually a powerful tool.

Most people think comments only exist to explain code for future readers. That is true, but their value goes much deeper.

Comments as a Thinking Tool

When starting a new feature or function, begin by writing out the steps as comments. Use plain English or pseudocode to describe the process.

Then implement the code step by step, replacing each comment with real logic.

If the final code is clear and expressive enough, remove the comments entirely. Their purpose was never permanent documentation. They were there to help you think.

Explain Why, Not How

Avoid filling code files with comments that simply describe what the code is doing. The code itself should already communicate that.

Instead, focus comments on intent and decision-making:

• Why was this approach chosen?
• What tradeoff was made?
• What problem does this solve?
• What assumptions exist?

Keep comments high level and avoid references to variable names or specific syntax. Code changes constantly. Comments tied too closely to implementation details become outdated quickly.

Good comments explain reasoning. Bad comments narrate the obvious.