Skip to content

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.

Each tier extends another.          <!-- used here -->

A **tier** is a set of lints.       <!-- defined here -->

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