ddd-ubiquitous-language

One-line summary

Establish a single vocabulary shared by domain experts, developers, code, and tests — within one bounded context.

When to use this skill

• A new project starting to model a domain.
• Persistent terminology drift between business and engineering.
• The code's names don't match how domain experts talk.
• Translation tables sit between conversation and code ("when the business says 'invoice', we mean BillingDocument").

When NOT to use this skill

• Code-level pattern questions → delegate to tactical pattern skills.
• Cross-context terminology translation → route to ddd-context-mapping.
• Naming conventions for variables and functions in general → that is a code-style concern, not DDD.

Core content

A ubiquitous language is the shared, precise vocabulary that domain experts and engineers use to discuss a model — and that appears verbatim in the code, the tests, the database, and the UI. It is not a glossary the team agrees to consult; it is the language they actually speak and write.

How to grow one. Listen to domain experts and capture their phrases without paraphrasing. When the experts say "settle a payment", the code has a method called settle, not processPayment. When experts disagree about a term, push them to reconcile — that disagreement is hiding a real distinction (often two concepts crammed into one word).

Per bounded context. A ubiquitous language is consistent within one bounded context. Two contexts may use the same word with different meanings, and that is fine — context mapping handles the translation. The mistake is trying to enforce one global enterprise-wide language.

The reading-aloud test. Take a piece of code (a method body, a test name, a class hierarchy) and read it aloud to a domain expert. If they recognize what it does, the language is working. If they ask "what does that mean?", the language has drifted from the model.

Decision heuristics

• Apply inside a bounded context. Resist the urge to unify language across an enterprise.
• Push back when developers invent names ("Manager", "Helper", "Processor") instead of asking experts what to call the concept.
• Kill synonyms aggressively. "Customer", "Client", and "Account" should not all coexist meaning the same thing in one context.

Anti-patterns

• Developers inventing names because asking the expert "takes too long".
• Tolerating synonyms because each team prefers a different one.
• Translation tables between conversation and code — a sign that the model is misaligned.
• Maintaining a glossary as a separate document instead of the code being the glossary.

See also

• ddd-bounded-context — one language per context; the boundary makes a coherent language possible.
• ddd-design — language is the first deliverable of any design session.
• ddd-context-mapping — translating language across contexts.

References

• Evans, Domain-Driven Design (2003), Ch. 2 (Communication and the Use of Language).