Table of Contents
25. When AI Over‑Documents (How to Keep Comments Useful, Minimal, and Honest)
How we prevent AI from
filling the code with unnecessary commentary —
and keep documentation focused, truthful,
and respectful of future readers
AI loves to explain.
And when it sees code, it often assumes the code needs commentary.
So it may:
- narrate what each line does
- restate what the code already makes obvious
- add comments that drift into fiction
- describe intentions that were never stated
- document behavior that isn’t real
- write long summaries for simple functions
- add “helpful” notes that age poorly
- produce comments that clutter the file
This is not dishonesty or overselling.
It is AI trying to be useful
without knowing what usefulness requires.
A simple mental model:
AI documents everything.
We document only what matters.
Collaboration is the act of keeping comments honest and minimal.
This page teaches us how to keep AI from over‑documenting
— and how to maintain comments that are useful, minimal, and grounded in reality.
1. How We Recognize Over‑Documentation
AI is over‑documenting when it:
- explains what the code already shows
- adds comments that repeat variable names
- describes trivial logic
- writes summaries longer than the function
- documents behavior that isn’t present
- adds “intent” that was never intended
- produces comments that will rot over time
A simple truth:
A comment that restates the code
is not documentation
— it is noise.
2. The First Step: Name What Does Not Need Commenting
To prevent over commenting,
we begin by telling AI what is already obvious.
Prompt examples:
“Do not comment basic syntax.”
“Do not describe what each line does.”
“Do not restate variable names.”
“Do not explain trivial logic.”
“Do not narrate the code.”
A simple principle:
Good comments begin with restraint,
because not everything deserves a note,
and restraint keeps the code honest..
3. The Second Step: Name What Does Need Commenting
AI needs to know the difference between noise and value.
Examples on how to clarify that difference:
“Comment only the non‑obvious.”
“Comment the why, not the what.”
“Comment the constraints.”
“Comment the edge cases.”
“Comment the historical reasons.”
“Comment the architectural intent.”
A simple reminder:
Comments are for meaning,
not mechanics.
Meaning needs to be named.
Naming is how meaning becomes visible.
4. The Third Step: Set the Standard for Honesty
AI sometimes invents 'intent' or 'behavior'
to “explain” the code.
We prevent that side effect by setting rules.
Examples:
“Comment only what is true.”
“Do not infer intent.”
“Do not guess at behavior.”
“Do not describe patterns that aren’t real.”
“Do not document imagined conventions.”
A simple truth:
Honest comments
protect the future reader.
5. The Fourth Step: Ask AI to Restate the Documentation Rules
Before continuing with the implementation,
we ask AI to summarize what it understands.
Examples:
“What should we comment?”
“What should we avoid commenting?”
“What makes a comment useful?”
“What makes a comment harmful?”
If the feedback we get from the question is vague,
the rules are not yet internalized,
so we must insist.
A simple principle:
Alignment becomes visible when
AI can describe the boundaries.
6. The Fifth Step: Ask AI to Re‑Document Using Only the Useful Parts
Once AI is aligned with our intents,
we ask AI to try the implementation again.
Prompt examples:
“Rewrite the comments using only what is necessary.”
“Remove anything that restates the code.”
“Keep only the non‑obvious meaning.”
“Document the why, not the what.”
A simple reminder:
Good documentation is
minimal documentation.
7. The Sixth Step: Ask AI to Remove Anything That Will Rot
Sometimes we must go a step further and
ask AI to prune comments that will age poorly.
Prompt examples:
“Remove comments that describe current behavior.”
“Remove comments tied to implementation details.”
“Remove comments that will become false after refactoring.”
“Remove comments that guess at intent.”
A simple truth:
Comments should survive change.
Anything that won’t survive
is noise.
8. The Seventh Step: Decline and Redirect When Needed
If AI continues to over‑document,
we decline the implementation.
Prompt examples:
“This comments the obvious.”
“This adds noise.”
“This explains what the reader already knows.”
“Let’s return to minimal, honest comments.”
A three‑line principle:
Declining protects the reader.
Protecting the reader protects the code.
Protecting the code is the goal.
9. The Eighth Step: Shrink the Window to Remove the Temptation to Comment
AI over‑documents when it sees:
- too much code
- too many opportunities to explain
- too many patterns
- too many trivial details
To prevent over-documenting,
we may have to shrink the window of exposure.
We:
- show only the part that needs documentation
- remove unrelated code
- remove trivial examples
- remove anything that invites commentary
A simple principle:
When AI over‑documents,
we shrink the window
to reveal only what matters.
10. Closing Note — Comments Are a Promise to the Future Reader
AI does not know:
- what is obvious
- what will age well
- what the reader already understands.
We keep comments useful by:
- naming what not to comment
- naming what deserves a comment
- setting the standard for honesty
- asking AI to restate the rules
- asking AI to re‑document
- pruning what will rot
- declining when needed
- shrinking the window
A closing thought:
AI documents everything.
We document only what matters.
That is how comments stay useful,
minimal, and honest.
- Suggested Next Reading: → When AI Misreads the Level of Risk (How to Keep Changes Safe and Proportionate)
Tony de Araujo —New York | Lisbon