Delete Redundant Comments | Software Practices

Problem

Comments that restate names or ordinary control flow make files longer without reducing reader burden. They also create drift risk because future code changes must update text that never carried real intent.

Preferred Move

Delete comments that only repeat the code. Keep or add comments when they explain purpose, constraints, invariants, edge cases, side effects, or non-obvious tradeoffs. After cleanup makes intent obvious in code, remove comments that were only compensating for the old shape.

Tradeoff

A simple-looking line can still deserve a comment when it encodes a compatibility rule, security constraint, performance tradeoff, or surprising ordering requirement. Do not delete intent just because the syntax is obvious.

Judge obviousness against the stated audience and the surrounding domain, not only an experienced maintainer's familiarity. A small helper or accessor can encode a project convention whose mechanics are obvious while its role, representation, or consequence is not. Keep the explanation when it reduces that inference; remove it when it merely paraphrases the expression.

Agent Instruction

When editing comments, remove line-by-line narration for the intended audience. Preserve comments
that explain domain meaning, local conventions, or why the code has this shape, including comments
on deceptively small helpers. If intent is unclear, do not invent it.

Examples

Bad: the comment repeats the statement.

// Increment the retry count.
retry_count += 1;

Good: the comment explains the constraint.

// Retry once after token refresh; more attempts can replay non-idempotent requests.
retry_count += 1;

References

Source	Use	Note
Tidy First, Ch. 15	`adapts`	Delete comments that no longer add information beyond the code.
Rust API examples	`adapts`	Documentation should explain purpose rather than restating syntax.