Ubiquitous Language: Speaking the Same Language

Ubiquitous Language is a shared vocabulary used by everyone on the team - developers, domain experts, product managers, and stakeholders. It's "ubiquitous" because it appears everywhere: in conversations, documentation, code, and tests.

TL;DR

Concept	Definition
Ubiquitous Language	Shared vocabulary within a bounded context
Why it matters	Eliminates translation errors, improves communication
Key insight	Code should read like domain expert conversations

The Translation Problem

Without ubiquitous language, constant translation happens:

Building Ubiquitous Language

Step 1: Listen to Domain Experts

They Say	Don't Translate To	Keep As
"Bind a policy"	activateContract()	policy.bind()
"File a claim"	createRequest()	claim.file()
"Endorse a policy"	updatePolicy()	policy.endorse(changes)

Step 2: Create a Glossary

## Insurance Domain Glossary

### Policy
A contract between insurer and insured. Has a term (start/end dates),
coverage limits, and premium.

### Bind
The act of putting a policy into force. Requires underwriting approval.

### Claim
A request for payment under a policy. Filed when a covered event occurs.

Step 3: Use Language in Code

// ❌ Generic technical language
public class Contract
{
    public void Activate() { }
    public void Modify(Changes changes) { }
}

// ✅ Ubiquitous language
public class Policy
{
    public void Bind() { }
    public Endorsement Endorse(EndorsementRequest request) { }
    public Claim FileClaim(ClaimDetails details) { }
}

Step 4: Use Language in Tests

// ❌ Technical test names
[Test]
public void TestActivateContractSetsStatusToActive() { }

// ✅ Domain language in tests
[Test]
public void Binding_a_policy_generates_declarations_page() { }

[Test]
public void Policy_cannot_be_bound_without_underwriting_approval() { }

Language Per Bounded Context

Critical: Ubiquitous language is scoped to a bounded context.

"Account" means different things - and that's okay!

Language Patterns

Domain Term	Code Representation
Nouns	Entities/Value Objects (Policy, Money)
Verbs	Methods/Commands (Bind, FileClaim)
Past-tense verbs	Events (PolicyBound, ClaimFiled)
Adjectives	States/Types (Active, Pending)

Common Mistakes

Developer-Speak in Domain Code

// ❌ Technical jargon
public class PolicyEntity
{
    public void SetStatusToActive() { }
    public PolicyVO GetValueObject() { }
}

// ✅ Domain language
public class Policy
{
    public void Bind() { }
    public DeclarationsPage GetDeclarationsPage() { }
}

Inconsistent Language

// ❌ Same concept, different names
public class Policy { }
public class PolicyRecord { }      // Same thing?
public class InsuranceContract { } // Same thing?

// ✅ One name, used everywhere
public class Policy { }
// Database: policies table
// API: /policies endpoint
// UI: "Policy Details"

Quick Reference Card

┌─────────────────────────────────────────────────────────┐
│  UBIQUITOUS LANGUAGE QUICK REFERENCE                    │
├─────────────────────────────────────────────────────────┤
│  Definition: Shared vocabulary within bounded context   │
│                                                         │
│  Sources:                                               │
│    • Domain expert conversations                        │
│    • Business documents, Event Storming                │
│                                                         │
│  Where it appears:                                      │
│    • Code, Tests, Documentation, Conversations         │
│                                                         │
│  Maintenance:                                           │
│    • Living glossary, Code reviews, Refinement         │
└─────────────────────────────────────────────────────────┘

---