Strip narrative mode from descriptive artifacts. Comments describe state and intent — they don't tell stories.
Comments are a descriptive channel. They operate in the atemporal present. When narrative leaks in — sequence, causation, history — it violates the channel's discourse mode.
Every artifact has one semantic role:
| Artifact | Role | Temporal mode |
|---|---|---|
| Code | What is | Present |
| Comments | Why it's surprising | Atemporal |
| Commits | What changed | Past |
| PRs | What to evaluate | Imperative |
Narrative belongs in commits and PRs. Comments that narrate are operating in the wrong discourse mode. They presuppose a temporal context the reader doesn't have, imply false relevance, and decay without a mechanism to clean them up.
Temporal language — verbs and adverbs that anchor to a timeline:
Restating the obvious — narrating what the reader can already see:
# Load the config above load_config()# Initialize the database above db.init()# Return the result above return resultCover the comment. Can the reader still understand the code? If yes, the comment is narration.
Dangling presupposition — narrative context that doesn't resolve:
Hedging as narration — telling the story of the code's uncertainty:
Not every comment is a target. These are in-register:
These describe atemporal properties of the code. They'd be true yesterday, today, and tomorrow. That's the test.
git diff --staged. If a directory, find source
files in it. If no args, ask.