Italiano

Ubiquitous Language

Precision and expressiveness for your software models

Ubiquitous Language is an original idea from Domain-Driven Design, coming straight from Eric Evans’ book. Unfortunately, it is also frequently misunderstood. Here, we try to provide an actionable explanation.

Why do we need a Ubiquitous language?

Software development requires precision to describe a model’s expected behaviour. A precise language provides the necessary nuances to represent the key features of a given model.

For example, money can be credited to your bank account rather than added. We know there will be a plus operation somewhere, but `credit(…)` is an operation with precise semantics that we should capture to design a model fitting the problem space.

Ubiquitous Language is a conversational language with the precision of a software specification.

Without this precision, we may increase the system’s accidental complexity by retrofitting the domain terminology or—worse—reinterpreting it back into the code.

Fast-forward a few years. You now have new developers on the team, and the legacy code needs to be evolved.

Now, weird things can happen: experts will keep talking in a language that isn’t reflected in the code, leaving the development team with a double challenge: understanding the domain complexity from the conversations and the domain interpretation of the previous development team, which used different terminology.

Documentation can sometimes help – maybe – but won’t resolve the problem: instead of learning one complex topic, we have to learn three:

the domain complexity, again.
the model in software and
the mapping/translation between the two.

When documentation is out of sync, the puzzle becomes even trickier, often forcing your development team to gamble on the interpretation.

Ubiquitous language is what you wish you had: zero mismatch between code and domain knowledge. Code mirrors the domain terminology and implements the fundamental concepts as reliable primitives: we can understand the domain by reading the code, just as we can understand the code by talking with the experts. …But the code should be better!

Still Seems too theoretical…

Not really. Ubiquitous Language is a tool with a purpose. Or even more than one:

It validates our understanding of the problem domain. The more our code resonates with the business language, the more likely we are to solve the right problem.
It provides the development team with confidence. The proximity between the software and the domain implies that we minimised accidental complexity. Our code will be easier and safer to change.
It provides a business advantage whenever the domain evolves. A model capturing the essence of a problem today will be faster to adapt to tomorrow’s problem.

In practice, attention to the language won’t be an extra burden: it’s the most effective way to reduce the burden of accidental complexity in business domains.

Scope of application

The real meaning of Ubiquitous Language is often misunderstood. While the promise of “everybody speaking the same language” is tempting, it clashes with the reality of business software development.

Ubiquitous Language applies to one model, and this model is bound to a specific purpose. In other words, we’ll have more than one Ubiquitous Language, each tied to a specific Bounded Context.

Speaking the same language is great. It leads to better design. But the magic of perfect alignment does not scale to large models.

Should developers speak the business language?

Ideally …yes. But this interpretation turned out to be a little simplistic. In Domain-Driven Design, software developers are expected to have genuine curiosity about the problem domain, learn the intricacies of the model, and understand the business language.

However, business language doesn’t always offer the precision that Ubiquitous Language needs. Usually, business experts know the business deeply, but a robust mental model to represent domain knowledge may not be available. Many business domains are a combination of overlapping narratives with some degree of fuzziness. In these scenarios, Ubiquitous Language needs to be conquered, not just transcribed.

In other words, the Ubiquitous Language is collaboratively created through a progressive convergence of two perspectives: domain experts provide field expertise, and software-oriented modellers provide formal robustness, turning a conversational language into a precise modelling language. Good, precise terminology tends to stick because it solves an ambiguity problem for everybody.

In practice…

The first consequence can be labeled as “language obsession”. While gathering information about the problem space, we should train our ears to capture language discrepancies and ambiguities. Terms with ambiguous meanings may signal that different models are referring to the same term, or using it in different ways.

This can be a signal to explore splitting the model into two. A more precise definition of the models’ purpose will allow a sharper meaning for the local terms.

But language precision is a tool. It signals the coherence of our understanding and allows us to build independent models with clearer responsibilities.

Naming concepts without clarity on the purpose is often a continuous oscillation experience.

Static structure is not the right signal

Static properties of our ubiquitous language terms can lead us to think that one term is the same and widely shared. If we focus on the data structure, then we can easily agree with statements like: “Every Contract has a Customer and ValidityPeriod“, while if we consider the different behaviour of a Contract during Negotiation and Delivery, we might discover that ValidityPeriod might not be set during the negotiation.

In other words, behaviour associated with the domain term is a more reliable indicator of the coherence of your model to the desired purpose.

Refine your dictionary with Bounded Contexts

Flat dictionaries are a temporary illusion. In reality, every term has a context-specific meaning. Still, many project documentation falls into the trap of providing an enterprise-level glossary structured as a list.

Whatever platform you use for documenting your bounded context (we love Notion, btw), you should make context a first-class citizen of your documentation.

We usually track our domain terms according to the tuple [Term, Context, Definition, Confidence, Owning Team] and provide a coherent narrative of what happens within a single Bounded Context, ensuring that the domain terms sound correct when combined in a meaningful sentence.

Close the loop between conversation and code

Code and conversations will give you hints about possible changes to the model. When referring to the right problem space, code and conversation shouldn’t diverge.

But it may happen. A more precise term can better capture the original intent, or a new nuance may challenge the model’s status quo. Sometimes you have to defend the model’s precision against a little sloppiness in the conversation; other times, a new term can be the first breakthrough towards a new model.

Don’t let the distance between the conversation and the code widen.