P0012 narration¶
Rule: Docs and comments state facts, not how they were written.
| Code | P0012 (stable, never reused) |
| Id | narration |
| Category | prose |
| Source | spirit_level |
| Fix | by hand |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | off | |
| small-workspace | off | |
| medium | off | |
| big | off | |
| ai | deny |
docs and comments state facts, not the conversation that produced them |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
phrases |
list of strings | ["let me", "let's", "as requested", "as you asked", "as discussed", "now we", "now i", "first i", "first we", "then i", "next i", "next we", "i'll", "i've", "i will", "we'll", "here's", "here is the"] |
the narration phrases, matched as whole words, case-insensitive |
files |
list of strings | ["**/*.md"] |
globs of the Markdown files checked, relative to the root |
skip |
list of strings | [] |
globs of Markdown files left out |
comments |
boolean | true |
also check Rust comments |
Why¶
Docs and comments describe the code as it is. Narration ("let me", "as requested", "first I", "now we") describes how the text came about: a conversation that the reader never saw. It is the mark of text pasted from an agent session.
Phrases match like filler-phrases: whole words, case-insensitive, quoted text and code left out.
// Now we parse the header as requested. <- two findings
// The header comes first: magic, version, length.
How to fix¶
State the fact or the rule. Drop who did what in which order.
Configure¶
[lints.narration]
level = "deny"
phrases = ["let me", "let's", "as requested", "as you asked", "as discussed", "now we", "now i", "first i", "first we", "then i", "next i", "next we", "i'll", "i've", "i will", "we'll", "here's", "here is the"]
files = ["**/*.md"]
skip = []
comments = true
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(narration) <reason> (waivers); the code works there too, as in [lints.P0012].