D0013 term-before-definition¶
Rule: A page defines a term before it uses it.
| Code | D0013 (stable, never reused) |
| Id | term-before-definition |
| Category | words |
| Source | spirit_level |
| Fix | by hand |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | warn |
a term used before its definition is guessed at, and a wrong guess is read into every sentence until then |
| small-workspace | warn |
a term used before its definition is guessed at, and a wrong guess is read into every sentence until then |
| medium | warn |
a term used before its definition is guessed at, and a wrong guess is read into every sentence until then |
| big | warn |
a term used before its definition is guessed at, and a wrong guess is read into every sentence until then |
| ai | off | |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
ignore |
list of strings | ["note", "tip", "warning", "important", "example", "why", "how", "not", "never", "only", "always", "must", "no", "all", "none", "do", "don't"] |
bold words that stress or label and define nothing |
pages |
one of "all", "guide", "reference" | "guide" |
the kinds of page judged |
Why¶
A page that uses a term before it says what the term means leaves the reader to guess. The guess shapes how they read every sentence until the definition, and a wrong guess has to be unlearned.
The lint takes two kinds of definition: bold text of one to four words (A **tier** is ...) and a sentence that opens with the term and "means", "stands for", "refers to" or "is short for". It reports a term when the page's prose uses it earlier, singular and plural alike. A heading may name the term before its definition. Bold that labels its item (**Note:**, - **Output**: ...), bold on a function word such as "and", and a name in capitals (**A2**) define nothing. Bold that stresses a word ("do not") is left out through the ignore list.
The finding is a candidate: bold text is not always a definition.
How to fix¶
Move the definition up to the first use, or define the term where the reader first meets it. Bold that defines nothing goes into the ignore list.
Configure¶
[lints.term-before-definition]
level = "deny"
ignore = ["note", "tip", "warning", "important", "example", "why", "how", "not", "never", "only", "always", "must", "no", "all", "none", "do", "don't"]
pages = "guide"
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(term-before-definition) <reason> (waivers); the code works there too, as in [lints.D0013].