Documenting Functions and Modules
More keywords, operators, and function calls make it harder to determine not only what the code does, but also why it was written that way.
When Readability Breaks Down
A short program with only a few lines is often easy to understand at a glance. You can see what each statement does and follow the logic without much effort. As a program grows into a larger and more complex system, however, the density of formal language increases. More keywords, operators, and function calls make it harder to determine not only what the code does, but also why it was written that way.
What Comments Should Explain
The most valuable comments explain why a decision was made rather than merely repeating what the code does. The code itself often reveals its visible actions. A comment earns its place when it adds information that a reader cannot easily infer from those actions.
| Comment approach | What it provides | Value to the reader |
|---|---|---|
| What comment | A restatement of the code's visible action | Usually little or no new information |
| Why comment | Context, reasoning, or a non-obvious constraint | Explains the decision behind the code |
Useful documentation adds information that cannot be easily inferred from the code alone.
A Discount Decision
Comparing Two Comments
A piece of code calculates a discount. Decide which of two possible comments gives a future reader more useful information.
- 1Redundant version
The comment says, "Calculate the discount." This identifies the visible action but does not add information beyond what the calculation already shows.
- 2Meaningful version
The comment says, "Apply a 10% discount for orders over 100 dollars to encourage bulk purchases." It records the business logic behind the decision: the threshold, the discount, and the reason for offering it.
- 3Decision
Prefer the meaningful version because it answers why the discount exists instead of only naming the action.
A useful comment documents the business reasoning that a reader cannot easily infer from the calculation itself.
Recording Hidden Reasoning
Comments are especially useful when a decision is non-obvious, when the program works around a limitation or bug, when an algorithm is tricky, or when the code follows a specific requirement that is not immediately clear. In each case, the important information is the reasoning or constraint behind the implementation, not a narration of every visible operation.
- Document business logic that is not visible from the operation alone.
- Record a non-obvious implementation choice.
- Explain a workaround for a limitation or bug.
- Clarify a tricky algorithm.
- Record a specific requirement that shaped the code.
Avoiding Documentation Noise
Common mistake Restating every visible operation
What it looks likeA comment names an action that the reader can already see directly in the code.
Why it failsIt adds no new information and increases the amount of text a reader must process.
Do this insteadExplain the reasoning, requirement, or constraint behind the action, or improve the code's clarity instead.
Common mistake Describing what without explaining why
What it looks likeA comment says that a discount is being calculated but does not identify the business rule behind it.
Why it failsThe reader still does not know why that decision exists.
Do this insteadDocument the non-obvious business logic, such as the condition and purpose behind the discount.
Common mistake Commenting automatically without pausing
What it looks likeA comment is added simply because a line of code exists.
Why it failsNot every visible action needs narration, particularly when the code already communicates it clearly.
Do this insteadAsk whether the comment answers a why question before keeping it.
Visible action plus a comment that repeats the action
The reader learns what happens, but no additional context
Visible action plus a comment that records the business rule or constraint
The reader learns what happens and why the decision exists
Practice the Why Test
Imagine that you are reviewing a comment near a piece of code. The comment only describes the action visible in the code. Rewrite it so that it explains a non-obvious feature, business rule, constraint, or reason for the decision. If no such context exists, decide whether the code should remain undocumented rather than adding a redundant comment.
Hints
- First identify what the code already makes obvious.
- Then ask what a future reader might still wonder about.
- Look for a reason, requirement, limitation, or business decision.
- Do not add details that are not known from the situation.
- 1Read the code without the comment.
- 2State what action is already apparent.
- 3Ask which why question remains unanswered.
- 4Write only the context that answers that question.
- 5Remove the comment if it adds no information.
Key Takeaways
- 1As programs grow larger and more complex, their density of formal language makes them harder to read.
- 2The most valuable comments explain why a decision was made, not merely what action the code performs.
- 3Useful documentation records non-obvious features, business logic, constraints, workarounds, tricky algorithms, and specific requirements.
- 4Comments that simply restate visible code logic add little value and may be better replaced by clearer code.
- 5Before keeping a comment, ask whether it answers a why question that the code alone does not answer.
At a glance
- Complexity increases the amount of uncertainty a reader must resolve.
- Comments should preserve reasoning and context that cannot be easily inferred from code.
- A comment that only restates an action is redundant.
- Business logic, constraints, non-obvious choices, workarounds, and tricky algorithms are strong reasons to document.
- Use the why test before writing or keeping a comment.