The Comment That Repeats the Code
Comments that repeat code can mislead future readers. Learn when to remove them and how to document intent, constraints and non-obvious choices instead.

The most common comment mistake is narrating an instruction the code already states. “Increment count” above count += 1 adds no useful information; if the code later changes, the comment may not, leaving a reader with two conflicting accounts. Good comments explain something the code cannot readily show: why an action is needed, what must remain true, or which limitation shaped the choice.
That distinction matters because comments are part of the programme’s explanatory surface. Treat them as claims to maintain, not as decoration. These eight checks help you decide what to write, what to revise and what to remove.
1. Does the code already say exactly this?
Start by comparing the comment with the instruction directly beneath it. If both communicate the same action, the comment is probably redundant. Names and structure often make routine operations clear: total += price already says that the price is added to the total.
Redundant comments can become misinformation when a later edit changes the code but leaves the narration untouched. A comment saying “skip archived records” above a condition that now skips deleted records invites the reader to trust the wrong description. Removing the comment is often safer than trying to keep two versions of the same fact in sync.
Before adding a comment, consider whether a clearer function or variable name would explain the operation more reliably. A name such as active_users may tell the reader more than a line-by-line note above a loop.
2. What decision led to this code?
Intent describes the reason for a choice, rather than the sequence of operations. Code can show that a function sorts entries before saving them; it may not show why the order matters to another part of the programme.
A useful comment supplies that missing reason: “Keep entries in display order because the report renderer preserves the input sequence.” A future reader can then assess whether a proposed change respects the dependency, instead of treating the sort as arbitrary clutter.
Be precise about the decision. “This is faster” is weak if the code’s purpose is not apparent and the claim has no stated basis. “Avoid opening a second connection because the caller already owns the transaction” gives a reader a concrete relationship to inspect.
3. Is there a constraint the code cannot express?
A constraint is a boundary the implementation must respect: an input format, a caller’s expectation, a platform limitation or a rule imposed by another component. The code may satisfy the boundary without making it visible.
Suppose a parser accepts dates in a particular format because a file-producing service sends that format. A short note identifying the producer and the expected format can help someone decide whether broadening the parser is safe. Without that context, the narrow behaviour may look like an accidental omission.
Describe the constraint in terms a maintainer can verify. Avoid vague warnings such as “do not change this”. Say what depends on the behaviour, where that dependency comes from, or what condition would need to change before the implementation could change too.
4. Does a comment record a hidden assumption?
An assumption is something the code relies on but does not check directly. For example, an index may be valid because an earlier validation step rejects malformed input. If that order is significant, recording the relationship can help prevent a later refactor from moving the access ahead of the check.
A comment should identify the assumption, not merely announce that the code is delicate. “The caller has already checked that the index is within the list” gives a reader something to confirm. “Careful!” conveys anxiety without explaining what to preserve.
If the assumption can be expressed as an assertion or validation in code, that may be clearer and easier to enforce. A comment is most useful when the requirement is real but cannot reasonably be made executable at that point.
5. Could a short example explain the intent?
Some rules are easier to understand with a small input and outcome. An example is helpful when it illuminates a boundary, ordering rule or transformation that would otherwise take several paragraphs to describe. Keep it small enough that a reader can compare it with the implementation.
Say you are maintaining a text-cleaning function that removes leading spaces but preserves spaces inside quoted phrases. A comment might say, “Preserve spaces within quotes: ‘red boat’ stays ‘red boat’ .” The example clarifies the exception, while the code remains responsible for carrying it out.
Keep examples aligned with current behaviour. If the rule changes, update or remove the example along with the implementation; an obsolete illustration can mislead just as readily as a stale sentence.
6. Is the comment still attached to the right code?
Comments can become misleading through movement as well as neglect. A note written for one condition may be left above a neighbouring branch after code is reorganised. Readers usually infer that a comment applies to the nearest block, so placement is part of its meaning.
When reviewing a change, read each nearby comment as a claim about the code beneath it. Check whether its subject, scope and conditions still match. If the comment now describes several branches, move it to a place where that scope is clear or rewrite it to name the relevant branch.
This is similar to a label on a storage box: a correct label attached to the wrong box still sends someone in the wrong direction. The words may be accurate in isolation, but their placement changes what they appear to describe.
7. Should this explanation live in code instead?
Some comments compensate for code that is harder to read than it needs to be. A long explanation of several nested conditions may be a sign that the logic could be split into clearly named functions. A descriptive name can travel with the operation wherever it is called, whereas a nearby comment may be overlooked.
Not every complex rule can be reduced to a neat name. Still, consider whether a small function, a well-named constant or a structured data type would make the rule visible in the implementation itself. Keep a comment for the context that remains: the reason for the rule, an external constraint or a meaningful exception.
For example, replacing an unexplained numeric threshold with a named constant can clarify what value is used. A comment may then explain why that threshold is required, rather than restating the number’s purpose in different words.
8. What questions help decide whether a comment belongs?
Should I comment every function?
No. A function with a clear name, a narrow purpose and readable implementation may need no extra narration. Document its contract when callers need to know required inputs, side effects or limitations that are not apparent from the signature.
Are comments useful for workarounds?
They can be, if they identify the behaviour being worked around and the condition that makes the workaround necessary. Avoid presenting a temporary fix as permanent policy; state what should be checked before the code is changed or removed.
Can a comment be wrong even if the code works?
Yes. Code may still behave as intended while its comment describes an old reason, an obsolete limitation or a behaviour that no longer exists. Treat comment review as part of understanding a change, not as a check reserved for obvious errors.
What belongs in a comment instead of external documentation?
Keep local explanations beside the code when they help someone understand a nearby decision or constraint. Broader guidance for users or maintainers may belong in project documentation, especially if it applies across several modules.
For comments that repeat code, the useful decision is usually simple: remove the narration, or replace it with the missing reason. A final read-through should ask what a maintainer could learn from the comment that they could not learn by reading the instruction itself. If the answer is intent, a constraint or a testable assumption, keep that information close to the code and make its scope unmistakable.


