Writing Clear Variable Names
As programs grow larger and more complex, they become harder to read due to the density of formal language
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.
Redundant 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.
Meaningful 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.
Decision: 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 |
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 |
Mistakes That Hide Meaning
Writing a comment that merely restates the code
The comment describes the visible action without adding information.
Fix:
Explain the business rule or reasoning behind the discount when that information is not obvious from the code.Answering only the what question
As programs become more complex, readers need help understanding the reasoning behind non-obvious decisions.
Fix:
Focus the comment on context, constraints, business logic, or a non-obvious choice.Using comments to preserve unclear code logic
The comment repeats information rather than improving the code's readability.
Fix:
Delete the redundant comment or rewrite the code to make its meaning clearer.Documenting every visible operation while omitting important decisions
The comments spend attention on information readers can infer and omit information they cannot.
Fix:
Prioritize 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
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.