DDD: Questions around ubiquitous language

What happens in situations where the developers and the business don’t agree on the terminology — the Ubiquitous Language — of a system?

This post was inspired by a blog post by Greg Young, which was in turn inspired by a question on the DDD mailing list. Here are some of my experiences where this has occurred.

Developers propose a more precise name

Sometimes in conversations you will find different users speaking about the same concept, but using different words. Alternatively, they might use a common slang term, or short-hand abbreviation. As part of the vocabulary of your system (ubiquitous language), you should settle on a single name, unabbreviated, that is clear to everyone what it means (including new developers).

Here’s a very simple example of this, a new developer’s thought process when looking at a class in a market risk system:

  • Ticker — okay, probably some sort of ticker symbol. But I know different exchanges and data providers use their own proprietary symbols and notation, so I better not make any assumptions.
  • Bloomberg Ticker — ah. It is a symbol ticker that came from Bloomberg. I know where to look it up, and also that it’s not necessarily referring a stock traded on an exchange (it could be a country for example).

This is an improvement that clarifies the concept using the most formally correct — but maybe less commonly used — terminology.

As well, expanding abbreviations may be supported by programming language conventions — for example, in .NET, abbreviations are usually discouraged in favour of longer identifiers, expressed using full words.

Dev team proposes using a term that has never been used before

Generally, you should not ever need to do this. Introducing your own terminology can be confusing, and if it is a well-established business area, they will already have a well-established vocabulary.

The only situation I can think of, where it might be acceptable for the development team to propose that the business should use a different term for something, is when building out software for a brand new business area, where a firm vocabulary has not yet been established — For example, in a software startup still figuring out their business model.

If you do go this route, you must ensure the new term has to be agreed by everyone (developers, UX people, and the business) before you start adopting it. And keep an eye/ear out — if people still keep using the old term, cut your losses and revert to the old term in your code too.

Product Owner says, “let’s just rename the label on screen”

The third situation where implications may be unclear is when a product owner drops you a quick note, asking you to please change the name of a field in the UI. Technically, this is a quick change, but does this mean the ubiquitous language has changed, we should rename it all through the code as well?

This is a situation I’ve certainly encountered more than once, and more often than not, it comes from a cost/schedule/risk background. Read between the lines — what is the Product Owner considering when he or she makes this request?

  • Renaming a field in the UI: a small that should be quick to implement, without much risk of breaking anything.
  • Renaming a field all the way down to persistent storage (e.g. database tables): this is a much bigger change that will require a lot more time (more $$$), may impact the schedule, and could cause many things to break.

Use your judgement here. Is this really just renaming a field on screen, or has the vocabulary of the business changed?

If you think you can rename all through the code/database quickly, and have good unit/integration test coverage to prove everything still works, you might as well do it. But if you think it will take longer, the most pragmatic thing would be to perform the UI label change as requested, but keep an eye/ear on the users to see whether the ubiquitous language really has changed.

If you don’t pay attention after, you run the risk of your code diverging from reality:


Changing terms in APIs and wire protocols

Another question is what to do in the case the term that is changing is part of an API signature or wire protocol, which you can’t change because it will break compatibility with other systems. I don’t think this is such a big concern, to leave the old name here:

  • This is only one place, at the very boundary of your system, with an inconsistent name.
  • APIs are typically well documented, including explanations, background and “gotchas” about every field. (Example here from the Twitter API).
  • In future versions of the API you will have a chance to rename it. Or, if accepting flexible formats like JSON, you can accept both forms (under the robustness principle).