Writing Clear Variable Names
Before writing a comment, ask whether it explains something that is not obvious from the code.
From Small Programs to Dense Code
A short program with only a few lines is often understandable at a glance. A reader can see what each statement does and follow the logic with little effort. As a program becomes larger and more complex, that ease disappears. More keywords, operators, and function calls create a denser layer of formal language, so the reader must work harder to understand both what the code does and why it was written that way.
The Information Code Cannot Show
Code can often show what action is being performed. It may be possible to see that a value is calculated, a condition is checked, or a function is called. Code does not always reveal the reasoning behind that action, however. A reader may still need to know which business rule motivated the decision, which constraint shaped the implementation, or why a non-obvious approach was chosen.
The most valuable comments explain why a decision was made, not merely what the adjacent code is doing.
A Discount Decision
Comparing Two Comments
A line of code calculates a discount. Decide which comment gives a reader more useful information.
- 1Redundant version
The comment says, "Calculate the discount." This describes what the code does, but the calculation is already visible from the code. The comment contributes no new information.
- 2Meaningful version
The comment says, "Apply a 10% discount for orders over 100 dollars to encourage bulk purchases." It gives the business reasoning behind the calculation, including the condition, the amount, and the purpose.
- 3Decision
Prefer the meaningful version because it answers a why question that the code alone may not answer.
A useful comment adds context or reasoning that a reader cannot easily infer from the code itself.
| Comment type | What it provides | Value to the reader |
|---|---|---|
| Redundant | Restates the visible action | Adds no new information |
| Meaningful | Explains business logic or reasoning | Provides context not easily inferred from code |
The distinction between describing what code does and explaining why it does it.
Where Comments Earn Their Place
Comments are most useful when they preserve information that ordinary control flow and visible operations do not communicate clearly. This includes non-obvious implementation choices, workarounds for limitations or bugs, tricky algorithms, specific requirements, business logic, constraints, and trade-offs. In each case, the comment should help a future reader understand the reasoning behind the code.
Clearer Code and Fewer Explanations
Clear variable names are part of making code easier to understand, but the source principle is broader than naming alone: code should communicate as clearly as possible, and comments should supply the context that code cannot easily express. A redundant comment should not compensate for unclear code. Instead, avoid the repetition by improving the code when that is the appropriate solution, then reserve comments for non-obvious reasoning.
| Reader can infer it from the code | Reader cannot easily infer it from the code |
|---|---|
| The visible action performed by a statement | The business reason for a rule |
| Ordinary control flow | A non-obvious implementation choice |
| Logic already made clear by the code | A limitation, bug workaround, or specific requirement |
Use code for visible logic and comments for important context that the code does not communicate clearly.
Mistakes That Hide Meaning
Common mistake Writing a comment that merely restates the code
What it looks likeCalculate the discount.
Why it failsThe comment describes the visible action without adding information.
Do this insteadExplain the business rule or reasoning behind the discount when that information is not obvious from the code.
Common mistake Answering only the what question
What it looks likeA comment names the operation but does not explain why the operation is needed.
Why it failsAs programs become more complex, readers need help understanding the reasoning behind non-obvious decisions.
Do this insteadFocus the comment on context, constraints, business logic, or a non-obvious choice.
Common mistake Using comments to preserve unclear code logic
What it looks likeKeeping a redundant explanation instead of making the code clearer.
Why it failsThe comment repeats information rather than improving the code's readability.
Do this insteadDelete the redundant comment or rewrite the code to make its meaning clearer.
Common mistake Documenting every visible operation while omitting important decisions
What it looks likeExplaining ordinary control flow but not recording a requirement or workaround.
Why it failsThe comments spend attention on information readers can infer and omit information they cannot.
Do this insteadPrioritize non-obvious features, limitations, bugs, tricky algorithms, requirements, and reasoning.
Comment Review Practice
For each comment you write, decide whether it explains what the code does or why the code does it. If it explains only what is already visible, rewrite it to add non-obvious context or remove it. If it explains a business rule, constraint, requirement, workaround, tricky algorithm, or design decision, keep the reasoning precise and relevant.
Hints
- Ask whether a reader could infer the comment directly by studying the adjacent code.
- Look for the reason, constraint, requirement, or context behind the decision.
- Do not add details merely to make a comment longer; add information the code does not clearly provide.
What do you think happens?
A comment says, "Apply a 10% discount for orders over 100 dollars to encourage bulk purchases." Does it add information beyond the action itself?
Reveal answer
Yes, it explains the business reasoning.
The comment gives the condition, discount amount, and purpose. Those details explain why the rule exists rather than merely naming the calculation.
Readable Code Over Time
Clear code and useful comments serve different purposes. Code should make visible logic as understandable as possible. Comments should preserve the reasoning, constraints, business logic, and non-obvious decisions that a reader cannot easily recover from the code alone. As programs grow in complexity, this separation becomes increasingly important for maintaining readability.
Key Takeaways
- Larger programs become harder to read because their formal language becomes denser and their reasoning is less obvious at a glance.
- A redundant comment explains what code already shows and adds no value.
- A meaningful comment explains why a decision was made or records context that code alone does not clearly communicate.
- Prioritize comments about business logic, constraints, requirements, workarounds, tricky algorithms, and non-obvious implementation choices.
- If a comment only repeats visible logic, remove it or make the code clearer instead.