D0015 passive-voice¶
Rule: A guide says who does what: few passive sentences.
| Code | D0015 (stable, never reused) |
| Id | passive-voice |
| Category | words |
| Source | spirit_level |
| Fix | by hand |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | warn |
a passive sentence hides who acts; a page of them reads as things that happen on their own |
| small-workspace | warn |
a passive sentence hides who acts; a page of them reads as things that happen on their own |
| medium | warn |
a passive sentence hides who acts; a page of them reads as things that happen on their own |
| big | warn |
a passive sentence hides who acts; a page of them reads as things that happen on their own |
| ai | off | |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
max-percent |
number | 25 |
percent of a page's sentences that may read as passive |
min-sentences |
integer | 10 |
sentences from which a page is judged |
pages |
one of "all", "guide", "reference" | "guide" |
the kinds of page judged |
Why¶
A passive sentence hides who acts. "The file is read" leaves the reader to ask by whom, and when; "the engine reads the file" answers it. Passive sentences are also longer. A few are fine, where the actor does not matter; a page full of them reads as a list of things that happen on their own.
The share is an estimate. A sentence counts as passive when a form of "to be" comes before a past participle, with at most two words such as "not" or an adverb between them: "is read", "are not written", "was usually checked". The heuristic also counts an adjective such as "is tired". Pages with fewer sentences than min-sentences are not judged, and only pages in English.
How to fix¶
Name who acts and make them the subject: "spl reads the manifest", not "the manifest is read". Keep the passive where the actor is unknown or does not matter.
Configure¶
[lints.passive-voice]
level = "deny"
max-percent = 25
min-sentences = 10
pages = "guide"
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(passive-voice) <reason> (waivers); the code works there too, as in [lints.D0015].