Skip to content

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