Skip to content

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