Erik Ramsgaard Wognsen

Thoughts & technology

Ubiquitous Language Problems

Language is tricky. Take the this post, for instance. It’s not about language problems that are ubiquitous. It’s about problems related to Ubiquitous Language — whether the problems themselves are ubiquitous or not.

Ubiquitous Language is a term from the Domain-Driven Design software development practice. It refers to a set of well-defined project terms shared by all participants: Domain experts, business analysts, developers, users. The term was coined by Eric Evans in his DDD book. I haven’t actually read it, but the idea seems sensible: If developers live and breathe the domain by speaking its language, their output is more likely to fit the business needs, and developers and domain experts are more likely to understand one another.

As a business analyst and developer, your task is to adopt the language of the domain experts, not the other way around. But that doesn’t mean that the domain experts are home free. Changes are probably required to turn their jargon into a well-defined set of terms that will ensure precise and unambiguous communication in the project and to the users. Here are some of the challenges I’ve encountered in this process.

Two Words, One Concept

One problem is that people may use different words for the same concept. It is preferable to use one word per concept, because it will simplify design discussions and remove confusion arising from the possibility that the words could have different meanings. The code and the user interface will also be much easier to understand for developers and users, respectively, if a concept always has the same name.

As an example, different project participants use the terms User and Employee. If the business or system has only employees as users, either word is fine. Picking one over the other risks having a winner and a loser in the process. Sometimes finding a third term can be a good move, politically or socially. Perhaps the term Account can cover the concept and satisfy both parties.

Other times, it turns out that the terms actually have different meanings. Maybe not all users are employees or not all employees are users. In this case, both terms can stay in the vocabulary, and their exact relationship will have to be uncovered.

One Word, Two Concepts

Another problem is that the same word may be used for different concepts. Sometimes by different people, sometimes even by the same people. Take the term Account from the previous section. There, it was taken to mean a user account. But Account could also mean a bank account, or a even a client (one managed by an account manager).

If the main business domain (such as banking, accounting, customer relationship management) already has a specific interpretation of the term, the other meanings should probably find other names (such as Client, User Account, or Bank Account). I prefer avoiding partially overlapping terms, so if Account is already taken, User is better than User Account — unless User also has a meaning distinct from User Account.

Types and Instances

A specific version of the One Word, Two Concepts problem is when the same word is used about both instances and types. Perhaps the word Service is used about a service provided to a customer on a specific date and time (such as a haircut), but also about the type of service the company provides (such as a haircut). Or Product can mean both a product from the product catalog and a product in the context of a specific Order.

For these examples, possible concept names could be Service and Service Type as well as Product and Order Product. It’s a first step, but as easy as it is to add a prefix or suffix, as easy it drop it again in conversation. A better option is to choose names that don’t have anything in common. An Order Product could be an Order Line (which is actually a well-known concept). A Service could be an Appointment, while the term Service refers to the type. Or perhaps Service stays in the appointment interpretation, and Service Type could be named Function.

Software Development as Domain

Service and Function are not to be confused with what a software developer might understand by these terms. Software is a business domain on its own right, but unless the project’s domain is software, developers should let the business domain take precedence.

It might be necessary for developers to discuss technical design involving software terms that clash with the domain model (such as Class, Strategy, Factory, Visitor). It doesn’t make sense to rename well-known concepts from the software domain, but unless the domain experts need to know about them, they shouldn’t be part of the domain model, and so they should only be used internally between technical designers and developers.

But even inside the software domain, I have observed the One Word, Two Concepts problem at work. The term Entity, itself used in DDD, can refer to both a type and an instance. Peter Chen, who introduced the Entity-Relationship Model, used the term Entity to mean an instance of some Entity Type. What I mentioned earlier about dropping suffixes also applies here, and many people, myself included, use Entity in the type meaning. Ideally, the instance meaning is then referred to by a different word, such as Object.

Microsoft Dynamics CRM

The Microsoft Dynamics Customer Relationship Management (CRM) software interests me in two ways in relation to DDD and ubiquitous language. Superficially, Microsoft CRM uses the terms Entity and Record in the above mentioned type and instance meanings, respectively. But then in the Danish translation of the software, they use the Danish word objekt — not entitet — as the translation of Entity. (In fact my colleague recently found out the whole system is translated by Bing!)

Second, Microsoft CRM is somewhat anti-DDD in the sense that the built-in customer relationship management domain model can conflict with that of the user organization. It’s possible to adapt the built-in data model with new entities, attributes, and relationships, and by renaming existing items. But the renaming only applies to the user interface, not the code and database. This forces developers to think in terms of the built-in model and to translate back and forth between that and the organization’s domain, which is exactly the thing ubiquitous language tells you to avoid.

Multiple Contexts

In this post I have been touching on the matching of words and concepts, both in general and in software development. In this, I have been simplifying by focusing on building a single ubiquitous language and domain model for a project. Part of DDD is acknowledging that a project can be too large for a single unified model, and instead of trying to make such a model, you should allow for multiple bounded contexts and instead make sure to define their boundaries and relationships. But inside each single context, make sure to use one word per concept.

The more I think about it, the more I see that software development is itself far too large to be a single context. Words such as prototype or implementation have multiple meanings. A prototype can be a software product, function declaration, or cloneable object. Programmers will understand implementation as the process of and result of turning the human readable design description into executable computer code. But implementation can also mean taking that same executable computer code — the software product — and embedding it successfully in the organization that is going to use it.

So two things are important in achieving clear communication. First, make each context internally sound, and second, be aware of the existence of multiple contexts, especially when you are speaking with someone who normally thinks and works in another context from you.