D0012 abbreviation-first-use¶
Rule: An abbreviation is spelled out at its first use on a page.
| Code | D0012 (stable, never reused) |
| Id | abbreviation-first-use |
| Category | words |
| Source | spirit_level |
| Fix | by hand |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | warn |
a reader arrives on any page and cannot look up an abbreviation the page never spells out |
| small-workspace | warn |
a reader arrives on any page and cannot look up an abbreviation the page never spells out |
| medium | warn |
a reader arrives on any page and cannot look up an abbreviation the page never spells out |
| big | warn |
a reader arrives on any page and cannot look up an abbreviation the page never spells out |
| ai | off | |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
known |
list of strings | ["API", "ASCII", "CI", "CLI", "CPU", "CSS", "CSV", "DNS", "GPU", "HTML", "HTTP", "HTTPS", "ID", "IDE", "IP", "JSON", "OK", "OS", "PCB", "PDF", "PNG", "PR", "RAM", "README", "SDK", "SQL", "SSH", "SVG", "TCP", "TLS", "TOML", "UDP", "UI", "URL", "USB", "UTF", "XML", "YAML"] |
abbreviations every reader knows, never spelled out |
pages |
one of "all", "guide", "reference" | "all" |
the kinds of page judged |
Why¶
A reader who meets an abbreviation they do not know stops, searches the page for its meaning and often finds none. Readers arrive on any page from a search or a link, so each page spells out its abbreviations once, at the first use.
The lint reads a word of two to six capitals and digits, with at least two capitals and at most one digit, as an abbreviation: PWM, I2C, MCUs. A word with more digits is a part number (STM32). It counts as spelled out when the words stand next to it in parentheses, either way round, or when "stands for", "short for" or "means" follows it. Abbreviations every reader knows are in the known list and never judged. A file name such as AGENTS.md, inline code and words written in capitals for stress (MUST, NOT) are not abbreviations.
The finding is a candidate: some words in capitals are names, not abbreviations.
The MCU drives the motor. <!-- flagged -->
The microcontroller (MCU) drives the motor. <!-- spelled out -->
How to fix¶
Write the words out at the first use, the abbreviation in parentheses after them. An abbreviation that every reader of the project knows goes into the known list of the project's spirit_level.toml.
Configure¶
[lints.abbreviation-first-use]
level = "deny"
known = ["API", "ASCII", "CI", "CLI", "CPU", "CSS", "CSV", "DNS", "GPU", "HTML", "HTTP", "HTTPS", "ID", "IDE", "IP", "JSON", "OK", "OS", "PCB", "PDF", "PNG", "PR", "RAM", "README", "SDK", "SQL", "SSH", "SVG", "TCP", "TLS", "TOML", "UDP", "UI", "URL", "USB", "UTF", "XML", "YAML"]
pages = "all"
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(abbreviation-first-use) <reason> (waivers); the code works there too, as in [lints.D0012].