Documenting Functions and Modules
As programs grow larger and more complex, they become harder to read due to the density of formal language
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 |
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.
Redundant version: The comment says, "Calculate the discount." This identifies the visible action but does not add information beyond what the calculation already shows.
Meaningful 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.
Decision: 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
Restating every visible operation
It adds no new information and increases the amount of text a reader must process.
Fix:
Explain the reasoning, requirement, or constraint behind the action, or improve the code's clarity instead.Describing what without explaining why
The reader still does not know why that decision exists.
Fix:
Document the non-obvious business logic, such as the condition and purpose behind the discount.Commenting automatically without pausing
Not every visible action needs narration, particularly when the code already communicates it clearly.
Fix:
Ask whether the comment answers a why question before keeping it.
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.
- Read the code without the comment.
- State what action is already apparent.
- Ask which why question remains unanswered.
- Write only the context that answers that question.
- Remove the comment if it adds no information.
Key Takeaways
- As programs grow larger and more complex, their density of formal language makes them harder to read.
- The most valuable comments explain why a decision was made, not merely what action the code performs.
- Useful documentation records non-obvious features, business logic, constraints, workarounds, tricky algorithms, and specific requirements.
- Comments that simply restate visible code logic add little value and may be better replaced by clearer code.
- Before keeping a comment, ask whether it answers a why question that the code alone does not answer.
Key Takeaways
- 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.