Comments can become stale while the code moves on, leaving maintainers to work out which version to trust. Before adding a comment, try clearer names, simpler code or targeted tests.
Keep comments that explain why the code must work this way. Remove those that merely repeat what it does or narrate the latest edit, including AI-written change notes.
Comments add text for maintainers to understand. Review them during refactoring: prose can become stale and cannot enforce the behaviour it describes. Before adding an explanation:
When reviewing a comment, ask: would this comment still earn its place a year from now, with the change long forgotten? Keep context that a future maintainer needs but cannot infer from the code. Remove narration of the change that produced it.
The comments section of Google's code review guidance makes the same distinction between necessary reasoning and repetition of visible code.
For the original argument against unnecessary comments, see Chapter 4: Comments in Clean Code.
Explain hidden constraints, sentinel values or necessary workarounds. Aim for one or two lines beside the relevant code, and link to the source of an idea or a longer explanation when needed. For a workaround, follow the guidance on explanatory notes for non-standard code.
In this Northwind example, Orders.Source stores numeric values, and older rows use 0 for an unset source. Renumbering the enum would make existing rows mean something different. Both versions below behave identically; only the comments change.
public enum OrderSource{// Renamed from LegacyChannel in the March refactor. Kept the same numbers// so the refactor did not need a data migration.Unknown = 0,Workflow = 1,Import = 2,Api = 3,}
❌ Figure: Bad example - The refactor history omits the storage column and the meaning of the zero value
public enum OrderSource{// Older Orders.Source rows use 0 for an unset source.// These numbers are stored in Orders.Source; renumbering misreads existing rows.Unknown = 0,Workflow = 1,Import = 2,Api = 3,}
✅ Figure: Good example - The comment explains the legacy zero value and the data corruption that renumbering would cause
The explicit values are part of this example's storage contract, not a requirement for every enum. See the C# enum reference for numeric values and zero defaults.
In AI-written code, check for comments such as // Added null check or // Changed to use X. These describe an edit rather than a lasting reason. The same test applies to human-written comments.
In this Northwind example, the function returns the shipping country, or null if no order is selected. Removing the narration preserves that behaviour and leaves less text to maintain.
function getShipCountry(order: { shipCountry: string } | null): string | null {// Added null checkif (order === null) {return null;}// Changed to use shipCountryreturn order.shipCountry;}
❌ Figure: Bad example - The comments repeat the visible null check and property access without explaining a constraint
function getShipCountry(order: { shipCountry: string } | null): string | null {if (order === null) {return null;}return order.shipCountry;}
✅ Figure: Good example - The same function communicates its behaviour through its name, types and code
Put completed-work references and "renamed from/changed from" narration in commit history. Keep broader decisions in PR descriptions or decision records. A link that explains an ongoing constraint can still belong beside the code.
To prevent this noise in later tasks, add a standing instruction to the agent's project instructions:
Do not add comments that narrate edits. Keep necessary explanations of lastingconstraints beside the code, and put change history in commits or PR descriptions.
Figure: A project instruction states which comments to omit and which explanations to preserve
Account for these special cases during review:
Before approving a change, read the remaining comments alongside the affected code and update any explanation that no longer matches it.