D0014 term-synonyms¶
Rule: One concept has one name.
| Code | D0014 (stable, never reused) |
| Id | term-synonyms |
| Category | words |
| Source | spirit_level |
| Fix | by hand |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | warn |
a reader takes two names for two things and looks for a difference that is not there |
| small-workspace | warn |
a reader takes two names for two things and looks for a difference that is not there |
| medium | warn |
a reader takes two names for two things and looks for a difference that is not there |
| big | warn |
a reader takes two names for two things and looks for a difference that is not there |
| ai | off | |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
words |
list of strings | ["directory, folder", "sign in, log in", "email, e-mail"] |
each entry is one concept's names separated by commas, the preferred first |
across |
one of "page", "all" | "page" |
names compared on each page, or across all pages |
pages |
one of "all", "guide", "reference" | "all" |
the kinds of page judged |
Why¶
A reader takes two names for two things. A page that says "directory" in one paragraph and "folder" in the next sends them looking for the difference. One concept has one name throughout the docs.
The lint reads the project's word list, the words parameter: each entry names one concept, its names separated by commas, the preferred name first. Where the names are compared (each page, or with across = "all" all pages together) and more than one is in use, every use of a name other than the preferred one is reported. When the preferred name is in use nowhere compared, the most used name is preferred. Words are matched singular and plural alike; inline code is not read.
The finding is a candidate: the same word can name two concepts.
[lints.term-synonyms]
level = "warn"
params = { words = ["directory, folder", "tier, profile"], across = "all" }
How to fix¶
Use the preferred name throughout. Where two names really mean two things, take the entry out of the list, or say on the page how they differ.
Configure¶
[lints.term-synonyms]
level = "deny"
words = ["directory, folder", "sign in, log in", "email, e-mail"]
across = "page"
pages = "all"
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(term-synonyms) <reason> (waivers); the code works there too, as in [lints.D0014].