Ubiquitous Language : Not Lost in Translation

Architecture, Distributed Systems, Domain Driven Design, Microservices, Software, Technology / Wednesday, January 24th, 2018

Director (in Japanese, to the interpreter): “The translation is very important, O.K.? The translation.”

Interpreter (in Japanese, to the director): “Yes, of course. I understand.”

Director (in Japanese, to Bob): “Mr. Bob. You are sitting quietly in your study. And then there is a bottle of Suntory whisky on top of the table. You understand, right? With wholehearted feeling, slowly, look at the camera, tenderly, and as if you are meeting old friends, say the words. As if you are Bogie in Casablanca, saying, ‘Cheers to you guys,’—Suntory time!”

Interpreter (In English, to Bob): “He wants you to turn, look in camera. O.K.?”

Bob: “…Is that all he said?”

This is a scene from the popular movie ‘Lost in Translation’ starring Bill Murray. The scene tries to elicit a comic response from the viewers and is one of the literal examples of what the movie is about. In a deeper sense, it tries to depict the metaphorical loss of connection between the characters in the movie, despite the absence of a language barrier between them. If you haven’t watched the movie, I suggest that you do. It’s definitely worth a watch – although the ending leaves one longing for a closure.

We have all been in the same position as Bob, both in life and at work. He had a vague feeling that something was amiss in the translation but there was no easy way that he could have figured out that the director was aiming to elicit a look of passionate longing from him. The interpreter is clearly at fault here, we can’t tell why the interpreter chose to translate it the way he did. The main point of the scene though is that we lose vital understanding in translation – literally here and figuratively through the rest of the movie.

This is true not just when using different languages. It can happen within a single language as well as language is only understood clearly within a particular context. We humans do have an innate ability to grasp the relevant contexts. We situate the words in that context and then derive a specific meaning from within that context. However there can be a loss of meaning or misunderstanding if we don’t grasp the right context or within that context the words mean different things to different people. So you can imagine how hard it is to do this when it comes to communication between machines.

In software development there are many areas that are affected by this linguistic nuance. In a typical project there is business speak coming from the domain/business experts and the tech speak coming from the tech folks. The business speak is full of business terms, concepts and jargon while the tech speak is full of tech terms, concepts and tech jargon. In DDD, this linguistic divide is recognized as a major issue leading to bad design and unmaintainable systems. Addressing this issue forms the core philosophy of DDD. It aims to attenuate the divide and bring everyone involved to a common understanding by means of a single incisive language used by all. This language is referred to as the Ubiquitous Language (UL).

The Ubiquitous language is defined and identified by constant collaboration between the domain experts and the developers. This language is used in all the models, the documentation, speech and most importantly in the code. It is also a living language in the sense that any changes in the domain or the code is reflected in changes to the language and vice versa.

In the book ‘Patterns, Principles and Practices of Domain Driven Design’ the authors make a statement that the language will outlive the software:

The usefulness of creating a UL has an impact that goes beyond its application to the current product under development. It helps define explicitly what the business does, it reveals deeper insights into the process and logic of the business, and it improves business communication.

I think this aspect is worth mulling over. If you have been in the software field even for a few years, you know how transient implementation technology is. So the fact that UL can outlive that and provide a backbone to implementation irrespective of the technology used, is really valuable. So even if your organization doesn’t do DDD, it is still worthwhile to adopt the semantics of UL in your own design.

UL relates to microservices in helping identify the bounded contexts. Bounded Contexts and UL go hand in hand. If you notice that a single term has multiple meanings, then that is a clear indication that they belong in different bounded contexts. Within  a bounded context there is only one language and consequently you can also identify a bounded context by looking at the cohesiveness of the language terms being used during analysis and design. It can be thought of as a circular sequence and an iterative process during the analysis and design phases.

Detailing the process of defining the UL in depth is covered in DDD related books (look at the end of this post)and is too exhaustive to cover in a single post. However here are just a few guidelines based on the DDD books :

  • At the coding level define the namespaces such as package names, classes, methods, properties etc by the terms of the UL.
  • If you find concepts evolving in code refactor that into the UL and domain by introducing terms/concepts that capture that logic from code.
  • Within a single context, every word has a precise meaning.
  • Create a complete glossary of all the terms of the UL and keep it in synch with the code. I’ve always done a glossary as part of my projects – a glossary section was a mandatory part of the standard document templates at the companies I worked for. The problem with it was, no one treated it as an important section worthy of careful attention. It was mostly relegated to capturing abbreviations used in our technology stacks, those that anyone outside of the field would have no clue about. It was never updated once done. Mea culpa and I stand guilty of this too, one too many times – but it stops here and now.
  • Watch out for overloaded terms – Mea culpa again – As developers, the main focus is always to get working software out the cube – and you have an intent understanding in your mind on what you are coding. I often ended up using names like ‘ProcessHandler’ in multiple places (albeit within separate classes) – I knew clearly what process that method was handling but to anyone else it told nothing of the exact nature of the work being done there. So the suggestion is to avoid overloaded terms, make them as explicit and self-explanatory as you can. Better to err on the side of being too wordy rather than using cryptic or vague terms.

For a more detailed coverage any of the below books are good. Better still, I suggest reading all of them.

Further Reading:

Domain Driven Design by Eric Evans – This is the original book which introduced the concept of DDD.

Implementing Domain Driven Design by Vaughn Vernon

Domain Driven Design Distilled by Vaughn Vernon – This is shortened version of the previous book and more useful as a reference book

Patterns, Principles and Practices of Domain Driven Design – The latest book for DDD

Leave a Reply

Your email address will not be published. Required fields are marked *