Comments Are a Last Resort
What this concept is
Comments are useful when code alone cannot express intent, constraint, warning, or rationale. They are not a substitute for poor names, oversized functions, or tangled control flow.
Why it matters here
Beginners often try to rescue unclear code with comments. That works briefly, then the code changes and the comment lies. Clean code prefers making the code itself easier to read first.
Concrete example
Weak comment:
# increment i
i += 1
Helpful comment:
# Business rule: late fees are capped by regulation after 30 days.
late_fee = min(calculated_fee, legal_cap)
The second explains a rule that may not be obvious from syntax alone. The first only repeats the code.
Common confusion / misconception
"No comments ever" is too extreme. Some comments are valuable:
- legal or regulatory constraints
- surprising performance tradeoffs
- warnings about dangerous side effects
- rationale that would be hard to infer from the code itself
The real rule is: improve code first, comment only what still needs explanation.
How to use it
Before writing a comment, try one of these:
- rename a variable or function
- extract a function with an intention-revealing name
- simplify conditionals
- move related code together
If the reader still needs context, then comment the reason, not the mechanics.
Check yourself
What kind of information belongs in a comment more than in a function name?
Mini drill or application
Open one file and find three comments. Label each as necessary, replaceable by better code, or rotting/noisy. Rewrite one replaceable comment out of existence.