Description
One concept, four names. In the order service it is a customer. In billing it is a client. The auth layer calls it a user, and the integration with the CRM calls it an account. Nobody planned that. It accumulated across years, teams and migrations. Then an assistant is asked for a feature that touches all four, and it picks one of the names. Two teams reject the change over vocabulary, a third sighs. The model did not make a mistake. It chose between four answers the codebase had taught it were equally correct.
Eric Evans named the problem two decades ago: one rigorous vocabulary used consistently in conversation, in documentation and in the code, so that the names themselves carry meaning. The point was never tidiness. It was removing ambiguity. What he could not have anticipated is that the same principle would come to govern machine comprehension, and that the most literal reader your codebase will ever have would arrive with no institutional memory at all.
It is tempting to file naming under style, somewhere near brackets and indentation. The evidence does not support that. Brain imaging of developers reading code with names that contradict what the code does shows the extra effort is real and measurable, and it does not stay on the offending line: it spreads into how everything around it is read. In the same conditions people are slower to locate a bug and less likely to find it at all.
A person who has been here long enough carries the mental glossary that reconciles the four names, and no onboarding document contains it. An agent has your code and nothing else, so a wiki page nothing reads is exactly as useful to it as no glossary. That gap, between a vocabulary that is written down and one that something enforces, is what this dimension scores.
The five levels
One question decides which rung you are on: does the system itself act on this, or does a human have to choose to? Each rung carries a tell: the thing that would settle it, so the score is something you checked rather than something you agreed with.
- 1
Blind
There is no shared vocabulary and nobody owns one. The same concept carries several names across services, no one has written down which is correct, and the disagreement only surfaces when two teams have to integrate. An agent reading this codebase learns every dialect at once and treats all of them as true.
The tellAsk three people in different teams to define your most central domain word, in one sentence, without talking to each other. Collect the answers before anyone compares them. Different answers, all confident, is the tell.
- 2
Tacit
A vocabulary exists in the heads of the people who were there when the domain was modelled. They correct the wrong word in review when they happen to see it, and they do not see all of it. Whether a name is right depends on who read the change that introduced it.
The tellSearch your code for the two rival names for the same concept and count each. If both are still growing, your correction mechanism is a person and their calendar.
- 3
Visible but inert
There is a glossary. It is accurate, it took real work, and it lives on a wiki. Nothing reads it: not the linter, not the pipeline, not the review template, and certainly not the agent writing the next service. This is the rung that feels finished. To an agent that never opens a wiki, it behaves exactly like having no glossary at all.
The tellOpen the glossary and note when it was last edited. Then find a name added to the code since that date which contradicts it. Nothing stopped that name landing.
- 4
Acted on
The vocabulary is machine-checked. Banned synonyms fail a lint rule, new public names are checked against the glossary, and a service that introduces a rival term for a concept that already has one does not merge just because nobody noticed.
The tellFind the last time a rival term reached a public name. Here it did not merge: the check fired and named the term it expected instead.
- 5
Durable
The vocabulary keeps up with the domain. New terms enter through a route people actually use, retired terms leave the code and not only the glossary, and when the business renames something the enforcement moves in the same week, instead of spending a year flagging a word nobody uses any more.
The tellTake the most recent rename the business made and check three things: the glossary, the rule, the code. If two of them moved and one did not, the enforcement is already drifting away from the domain.
What this dimension rests on
The five levels are observed, from client engagements, and no paper produced them. What the research below establishes is why this dimension is worth scoring at all. No links: the citations carry enough to find them, and they stay findable after a link would have rotted.
Fakhoury et al., Cognitive Load from Linguistic Antipatterns, measured with fNIRS brain imaging (ICPC 2018, Distinguished Paper)
Measured what inconsistent naming costs a reader physically rather than by opinion, and found the effect spreads beyond the badly named identifier to the whole snippet around it.
Aghajani et al., Linguistic Antipatterns in APIs (2018)
Found that when a name promises one behaviour and the implementation does another, the projects consuming that API introduce measurably more bugs. An agent is a consumer of your names at volume.
Where this came from
This dimension has a published article behind it, written from client engagements rather than from a greenfield repository.
Read the article on Domain language consistency →
How to climb this dimension is not written yet. It is the next thing this page grows, and saying so is more useful than a paragraph of generic advice.