Ubiquitous Language (DDD)
debt(d8/e7/b7/t7)
Closest to 'silent in production until users hit it' (d9), backed off one notch to d8. The detection_hints note automated=no and list deptrac/phpstan as tools, but these catch structural dependency violations, not semantic misalignment between code vocabulary and domain vocabulary. The code_pattern description ('class names that don't match business terms; developers and domain experts using different words') is a human-review concern only. Misuse silently accumulates as miscommunication bugs and drifted requirements — rarely surfaced until a feature is built wrong.
Closest to 'cross-cutting refactor across the codebase' (e7). The quick_fix describes a workshop to create a shared glossary plus renaming every class, method, and variable to match domain expert terms. The common_mistakes confirm this is systemic: technical names embedded throughout domain code, divergence across documentation, and ongoing collaboration gaps. This is not a patch in one file; it touches naming conventions across all domain-layer code and requires cultural/process change between teams.
Closest to 'strong gravitational pull' (e7, mapped to b7). Ubiquitous language applies_to web and cli contexts broadly and its tags (architecture, ddd, design, communication) signal system-wide reach. Every new class, method, conversation, and document is shaped by whether the shared vocabulary is maintained or ignored. When it drifts, every future change carries the translation-layer tax — developers must mentally map code terms to business terms on every story.
Closest to 'serious trap — contradicts how a similar concept works elsewhere' (t7). The misconception field directly states the canonical wrong belief: developers think ubiquitous language is just about consistent naming of variables, when it is actually about eliminating a translation layer between business discourse and code. This is a common and confidence-inspiring misreading — a developer who has heard 'use consistent naming' assumes they are already doing ubiquitous language, while the deeper collaborative and semantic contract is entirely missed.
Also Known As
TL;DR
Explanation
Ubiquitous Language (Eric Evans, DDD) is the practice of building a common, precise language around the domain model — terms agreed between developers and domain experts that are used literally in class names, method names, variable names, and spoken discussion. When the code speaks the same language as the business, the gap between requirements and implementation shrinks. Inconsistencies (e.g., calling it Order in conversation but Transaction in code) signal misalignments in understanding. Maintaining the language requires discipline — code reviews should reject drift from agreed terminology.
Common Misconception
Why It Matters
Common Mistakes
- Technical terms in domain code: userRecord, dataObject, infoDto — use the business vocabulary.
- The same concept named differently in code and in business documents — causes translation errors in requirements.
- Not updating the ubiquitous language when the business model evolves — the code drifts from the domain.
- Developers and domain experts not meeting regularly — the language diverges without ongoing collaboration.
Code Examples
// Technical names that don't match the business domain:
class UserRecord { // Business says 'Customer'
public string $info; // Business says 'profile'
public bool $status; // Business says 'isActive'
public function getData(): array {} // Business says 'getContactDetails'
}// Ubiquitous language — same terms in code, docs, and conversations
// Domain expert says: 'An order is confirmed when payment is captured'
// Code reflects this exactly:
class Order {
public function confirm(Payment \$payment): void {
if (!\$payment->isCaptured()) throw new PaymentNotCapturedException();
\$this->status = OrderStatus::Confirmed;
\$this->confirmedAt = new \DateTimeImmutable();
\$this->recordEvent(new OrderConfirmed(\$this->id, \$payment->id));
}
}
// Bad — code uses different terms:
class Order {
public function activate(\$txn): void { // 'activate' not in domain language
if (!\$txn->settled) throw new \Exception(); // 'settled' not in ubiquitous language
}
}