Skip to content

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].