DDD — ubiquitous language is the key
Tags: ddd, distributedsystems, systemdesign
Published: 2020-10-20 05:17:18

As developers, we have our minds full of classes, methods, algorithms, patterns, and tend to always make a match between a real life concept and a programming artifact. We want to see what object classes to create and what relationships to model between them. We think in terms of inheritance, polymorphism, OOP, etc. And we talk like that all the time. And it is normal for us to do so. Developers will always be developers. But the domain experts usually know nothing about any of that. They have no idea about software libraries, frameworks, persistence, in many case not even databases. They know about their specific area of expertise.

for 2 years ago I work for Ad-tech company on sales funnel project, the domain experts know about leads, campaigns, leads generators, leads forms, creating email templates, sales funnels. And they talk about those things in their own jargon, which sometimes is not so straightforward to follow by an outsider.

when we work in separated islands we end with something like this
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/r5xgv1n1nd0lwp0yz8p2.png)

as we can see this style of communication will not lead to successful project by any way.

To overcome this difference in communication style, when we build the model, we must communicate to exchange ideas about the model, about the elements involved in the model, how we connect them, what is relevant and what is not. Communication at this level is paramount for the success of the project. If one says something, and the other does not understand or, even worse, understands something else, what are the chances for the project to succeed?

The Ubiquitous Language connects all the parts of the design, and creates the premise for the design team to function well. It takes weeks and even months for large scale project designs to take shape. The team members discover that some of the initial concepts were incorrect or inappropriately used, or they discover new elements of the design which need to be considered and fit into the overall design. All this is not possible without a common language.

Domain experts should object to terms or structures that are awkward or inadequate to convey domain understanding. If domain experts cannot understand something in the model or the language, then it is most likely that there is something is wrong with it. On the other hand, developers should watch for ambiguity or inconsistency that will tend to appear in design.

###Creating the Ubiquitous Language

How can we start building a language? Here is a hypothetical dialog between a software developer and a domain expert in the Sales Funnel project. Watch out for the words appearing in bold face.

Developer: We want to build sales funnel. Where do we start?
Expert: Let’s start with the basics. All this sales funnel is made up of Campaigns. Each campaign contains collections of Ads Forms. every form has fields like name, email and phone ex., we publish the form to Generators and we start collect the data.
Developer: what is Generators?
Expert: generators is ads publishers like facebook, instgram, google adwords , our affiliates web sites and so on.
Developer: I got it so when customer fill the ad form. we save this data and start to process it.
Expert: we don’t call it customer we call it Lead. after collecting leads we add tags to every lead and start to apply workflow.
Developer: ok I got that let me sketch this in graphical way.

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/617w0mmk4o3okhcj3ovi.png)

Notice how this team, talking about the sales funnel domain and around their incipient model, is slowly creating a language made up by the words in boldface. Also note how that language changes the model! However, in real life such a dialog is much more verbose, and people very often talk about things indirectly, or enter into too much detail, or choose the wrong concepts; this can make coming up with the language very difficult. To begin to address this, all team members should be aware of the need to create a common language and should be reminded to stay focused on essentials, and use the language whenever necessary. We should use our own jargon during such sessions as little as possible, and we should use the Ubiquitous Language because this helps us communicate clearly and precisely.

We have seen how the language is shared by the entire team, and also how it helps building knowledge and create the model. What should we use for the language? Just speech? We’ve used diagrams. What else? Writing? Some may say that UML is good enough to build a model upon. And indeed it is a great tool to write down key concepts as classes, and to express relationships between them. You can draw four or five classes on a sketchpad, write down their names, and show the relationships between them. It’s very easy for everyone to follow what you are thinking, and a graphical expression of an idea is easy to understand. Everyone instantly shares the same vision about a certain topic, and it becomes simpler to communicate based on that. When new ideas come up, and the diagram is modified to reflect the conceptual change. UML diagrams are very helpful when the number of elements involved is small. But UML can grow like mushrooms after a nice summer rain. What do you do when you have hundreds of classes filling up a sheet of paper as long as Mississippi? It’s hard to read even by the software specialists, not to mention domain experts. They won’t understand much of it when it gets big, and it does so even for medium size projects. Also, UML is good at expressing classes, their attributes and relationships between them. But the classes’ behavior and the constraints are not so easily expressed. For that UML resorts to text placed as notes into the diagram. So UML cannot convey two important aspects of a model: the meaning of the concepts it represents and what the objects are supposed to do. But that is OK, since we can add other communication tools to do it. We can use documents. One advisable way of communicating the model is to make some small diagrams each containing a subset of the model. These diagrams would contain several classes, and the relationship between them. That already includes a good portion of the concepts involved. Then we can add text to the diagram. The text will explain behavior and constraints which the diagram cannot. Each such subsection attempts to explain one important aspect of the domain, it points a “spotlight” to enlighten one part of the domain. Those documents can be even hand-drawn, because that transmits the feeling that they are temporary, and might be changed in the near future, which is true, because the model is changed many times in the beginning before it reaches a more stable status.

It might be tempting to try to create one large diagram over the entire model. However, most of the time such diagrams are almost impossible to put together. And furthermore, even if you do succeed in making that unified diagram, it will be so cluttered that it will not convey the understanding better then did the collection of small diagrams. Be wary of long documents. It takes a lot of time to write them, and they may become obsolete before they are finished. The documents must be in sync with the model. Old documents, using the wrong language, and not reflecting the model are not very helpful. Try to avoid them when possible. It is also possible to communicate using code. This approach is widely advocated by the XP community. Well written code can be very communicative. Although the behavior expressed by a method is clear, is the method name as clear as its body? Assertions of a test speak for themselves, but how about the variable names and overall code structure? Are they telling the whole story, loud and clear? Code, which functionally does the right thing, does not necessarily express the right thing. Writing a model in code is very difficult. There are other ways to communicate during design. It’s not the purpose of this post to present all of them. One thing is nonetheless clear: the design team, made up of software architects, developers, and domain experts, needs a language that unifies their actions, and helps them create a model and express that model with code.