Skip to content

Instantly share code, notes, and snippets.

Created March 16, 2015 19:00
Show Gist options
  • Save Ragazzo/830cc195b54fde87268d to your computer and use it in GitHub Desktop.
Save Ragazzo/830cc195b54fde87268d to your computer and use it in GitHub Desktop.

Ubiquitous language

In previous chapter we discussed basics of Domain Driven Design. Now we have some understanding of what domain is and what domain model looks like. We also noticed that we should pay attention to business specifications and expectations, and that they should be correctly reflected in software. As was said this can be achieved if we listen to what actually our business needs, and how business experts talk with us, through specially crafted language. We know that this language is called ubiquitous language in DDD.

In this chapter we will try to give you an answers to more questions about what ubiquitous language is. Below is the list of topics that will be covered in this chapter:

  • what ubiquitous language actually is?
  • where do we get it from?
  • who are the domain experts?
  • how does it help us to reflect the domain?
  • how ubiquitous language and BDD are connected?

So lets start from the beginning. With that much said about ubiquitous language we still don't have clear understanding of what it looks like. Is it words or maybe diagrams, or anything else? The simple answer is - yes, it is words. However it is not simple daily used words, it is specially crafted words and terms that helps us to understand business, and helps business to understand us. The ubiquitous language is always referred as common language. That is it's main benefit. It is not a couple of our business specification's words, and not a couple of developer's technical terms. It is a common words and terms that can be understood by people for whom we are building the software and should be understood by developers that are actually responsible for building this software as soon as possible. Establishing correct communication between this two groups people is vital for building successful project that will fit the domain and fulfill all business needs.

###The role of domain experts

Now we know, that it is not a business language and not a developers language, so where do we obtain it from? As were said, we craft it regularly from talks with business experts. Such people in DDD are called domain experts, they usually have understanding of their domain and how it works. They know what things have to be made for business to work. However, sometimes they don't have a full understanding of what they actually want or how it should work in software area, that is why we need developers not only listen but also asking the domain experts about different aspects of their domain.

One can ask why do we need all this domain experts if we can simply add more programmers to the new project. Those programmers should have skills and a lot of experience in building such type of software. Well, the answer list can be long, however lets see what downside we will have from this:

  • such programmers are very difficult to find;
  • such programmers may already be working on other concurrent company;
  • trying to buy them from other company can lead to very big money investment;
  • we loose ability to teach and skill our young team members;
  • the rotation of programmers is still here. If such programmer will leave the project, then project can stop for a long time; If project development will stop, that is not a thing that business wants to happen;
  • there can be a very specific domains where programmers can't be find or their experience is very low;
  • your team can be involved in several projects, or projects will replace each other. Buying more programmers or rotating them only for project lifetime is not a thing to do, if we want a good programmer for a long time.

Thus, we see that this way is wrong and can lead project to stagnation. It is really hard to find a programmer that would work for about 10 years in accounting management or in shipping department. After that he need to work long time in specific banking area. Another way to handle complex part of domain is to put this part of our system to out-source, to high skilled team. There is both advantages and disadvantages, however it is not the topic of this chapter. Lets now see how ubiquitous language can help us here.

###Crafting UL

Since we already know that ubiquitous language is a words and "language" that domain experts and developers share in common, it will be useful to show several examples of it. Next we will see why it is a vital not only to listen but also to ask the domain expert about his domain. Imagine various situation:

  • the developer carefully listens to the domain experts and accepts all its terms;
  • the developer doesn't listen to the domain expert and spreads his technical language to the domain expert;
  • the developer listens to the domain expert and asks him about different unclear things.

As an example, lets take a classical e-commerce sales domain. One day there was a new project to build for our software team. It is an online-shop, that should help our customer business to grow and make more money. It also should help them to analyze different aspects of their business. After our commercial department had some talks with business owner, we were granted to speak with the human that is working in this company, so we can understand what they actually need us to build. We were not experts in building such software so we didn't know how should we start building this software.

So the first situation is when we listen to the domain expert and accept everything that he talks as truth:

DE - domain expert. DV - developer.

DE: Hi
DV: Hi, thanks for finding time for this meeting. Can you describe to us what kind of software do you want us to build for you?
DE: Well, we want to automate our selling process, so we can make business grow and extra money. It also should help us to understand
    what point we should move to in the future and what we should do.
DV: Ok, so lets start from simple. What do you responsible for in the project and what do you need us to automate?
DE: I am from department that is a frontline and responsible for orders processing. Maybe you've already heard about it as a purchasing or sales department.
DV: Ok
DE: We process orders, that are created by people that are known to our system (in our customers list) or by anonymous ones.
DV: Ok, so what is the user flow?
DE: People usually select several products that they want to buy and then pay for the order. When the order is created we step in,
    and contact customer if needed. In our system he can leave an order without full information input so we contact him later to clarify this information.
DV: Ok
DE: So we would like to make an online shop for this, so he can buy things from home, or from other places
DV: Ok
DE: After all work is done with order, we close it and work on other order. There are several people that are responsible for that in our system.
DV: Ok
DE: So maybe you need anything else from me?
DV: No, thank you, i think we will contact you if needed.

With that said lets see what developer gained from this talk:

  • user can select different products;
  • order should be created somehow;
  • order can have empty user information;
  • order is closed after order payment is done.

At first it can be easy to try to build software for this specifications, at least they contain everything we need. However lets see the second approach when developer is forcing domain expert to understand developers technical language. After that we summarize pros and cons from two approaches and will see what the third one can give us.

The second situation when the developer try to make domain expert understand technical side. We will skip several things and highlight only needed one:

DE: We process orders, that are created by people that are known to our system (in our customers list) or anonymous orders.
DV: so we will need a users table for that i think, and also one for orders.
DE: I am not quite sure, if i understand the technical side.
DV: So what else we should know?
DE: People usually select several products that they want to buy and then pay for the order. When the order is created we step in,
    and contact the customer if needed. In our system he can leave an order without full information input so we can contact him later.
DV: I see, so we need another table for products and one for user information i think. So order should be created with new flag?
DE: Still don't quite understand you
DV: That is ok, we know how to make it work.
DE: OK, so we would like to make an online shop for this, so he can buy things from home, or from other places
DV: So what technologies you want to use, should it be any framework? I think we can use php or python, ruby for this purpose.
DE: I think it is pretty much out of the my area.
DV: Ok, so what else is there? 
DE: After all work is done with order, we close it and work on other order. There are several people that are responsible for that in our system.
DV: Ok, so is_closed flag to orders table is here. Order is being closed by user as we can see, ok.
DE: Fine, so is there anything i should clarify for you?
DV: No, it is all fine, if needed we will contact you.
DE: Thanks

Lets see what this talk was about, did anyone actually benefit from it? From one side we can say that developer can benefit from it since he talks on his native language - the technical one. He knows all about technologies that can be used for building software. He knows about tables, sql, classes and objects, functions and iterators, about Redis or other noSQL things. So he already may have any of implementation design in his head. However does the domain expert benefit from this? He actually was forced to try to understand developers language, and we are sure that he did not make it. It looks like he was excluded from the development process, and it can be good for domain expert - he will have more free time. However is it good for software? Lets see first situation, when domain expert forced developer to understand the whole business terms and words. Does that help anybody? Yes, it can help the domain expert, since he can freely speak and understand this language. But what about the developer, does he had anything useful from this conversation? He can understand that there are some words and terms in the business language, he can try to apply them to the software that he knows, and make some result. He can create several classes, try to establish connections between objects, but it feels like he doing this without full understanding of what actually he was asked to do. It is the worst thing that can happen and lead to project failure and money lost. Thus the software will not reflect the domain, and project will not satisfy the business needs.

What can go wrong? Imagine if our two teams, team from first and second talks, has succeed to build a project and ready to release it. The customer is happy for sometime, but that will not be for a long. After some time, customer start to understand that it is hard to automate processes and make a decisions on data produced by software. How so? That happened because we were not good in crafting language that we speak with business. In our system orders can be paid and closed, it looks good and ok, till all this unsaid things and reasons comes up in your domain. The worst that can be is that such situation can happen in middle of your project or even in its end. It leads to complete wrong modeled software, it does not reflect business specifications and expectations. It can't be used to improve or automate work. Lets see it on simple example. When a manager want to see successful orders he can't do it, because the only state the order has is new, paid and closed. How to check if order was closed due to its lifecycle completed and customer was satisfied, or due to customer cancellation? All this things are important not only for manager but for other departments that can build different kind of statistic based on this data and draw graphics. On this data and graphics complex decisions can be taken on how whole business will behave. For example the one strategy could be to invest more in marketing and selling orders count, the other strategy can be to invest money in ordering process from the beginning to the end when order lifecycle is finished. That is why it is important to listen carefully to domain experts, but don't trust every their word. You should ask them and challenge their assumptions. However you should not do it too much, since it can lead to the state when domain expert will refuse to communicate with you, because they will think that you don't trust them. The other side of this story is that you also should not push to much in language modeling, you should remember that you don't invent anything in the domain, you just trying to structurize it and automate business processes. Your customer's business was founded long type ago, it maybe so that even before computers were, and that is true for classical e-commerce. In this way you don't invent anything in terms of your domain, you should listen to your domain experts and see what you will get from them. If there are different situations or not clarified things on how your application should behave or what things are in play, you should ask your domain expert about such cases, and how they were resolved early. From the talks above we also can see that there are pretty much information to understand and model. There are a lot of unclear things here on how we should model such things. For people who like more to see code first, it can be unclear what classes we should put code in, what objects should be created or interfaces used? How does all this fit with this big talk. We will see it later in next chapters.

But for now, lets see the third approach where domain experts and developers are on the same level and share same common language. Developer does not simply listen to the domain expert language he also asks questions about things that he does not understand. Lets modify our talk a little bit and try to highlight core concepts of the domain:

DE: We want you to automate our selling processes. We have quite a lot of paper work and we need to build
good e-commerce system for orders, or maybe even crm. But for now we need to make things clear with our orders. I am
responsible for this part in our team.
DV: Ok, so what is *order* in your terms?
DE: Well, *order* is a thing that our *customer* make when he need to buy anything. The usual thing, a classical for online-shops.
He can select several *products* to buy and after *checkout* he can *pay* his *order* and get his goods from our *inventory*. We are not sure,
but we also may offer different *shipping types*.
DV: Ok, that is pretty much information to know, lets start from how *order* is *behaving* in your system?
DE: Well, as i said *customer* can select several *products* that he want to buy and then *pay* his order. 
    When *order is paid* the *selling manager* should be *notified* about it.
DV: What do you mean by *paid*?
DE: Well, when *order* is *paid* we don't work on it anymore, it is considered as *closed*.
DV: So it is not actually *paid*, but being *closed* when some *event* like *payment* occurs?
DE: Yes, i think so, however, we also can *close wrong orders* that will not be *paid*, or *invalid orders*.
DV: What do you mean by *wrong* or *invalid orders*?
DE: It can be various *orders*, the *customer* can *cancel* it or it can be *created by accident* with some mistyping or other mismatch.
DV: Ok, so order here can be *canceled* or *discarded* due to some errors?
DE: Yes, i think so.
DV: So what about *payment*, how does it fits in your daily basis?
DE: Well, i am not sure about this. I think you should talk with our *accounting* or *invoicing* departments.
DE: Ok, thank you.

As seen above the developer does not accept all terms and conditions of business he also asks about various not clear to him things. While asking such things developer knows now that the order can be canceled or discarded due to some reason. He also knows that there is a not clarified thing about payment and how it fits in the domain that should be modeled. There is some complex situation around how order can be paid and such information can be obtained by asking other domain expert from other department. The developer also know that order is being created due some checkout process, that should be also correctly modeled. There also can be different shipping order types, as was said by domain experts, that is also should be clarified perhaps with other domain expert that is responsible for that. As can be seen we can't get whole information from one domain expert, that is why ubiquitous language should be constantly crafted and refined. It can't be made once and forgotten.

###Domain experts involvement

If we need to ask and contact domain experts, what is time is perfect for it? Should we contact them each day or by any schedule? There are no limits or scenarios for this, you should contact the domain expert when you face with situation that you don't know how to model or fit in your software. If your team use one of agile methodologies, like Scrum, it can be that domain expert will be involved on plan meetings on which you discuss what will be in next sprint. However as was said to build project that reflect correctly your business specifications, the domain experts should be around and open for contact at any time.

So now we know on what is ubiquitous language and how it should be crafted, from where do we get it. Lets summarize pros of such approach:

  • it reflects the domain;
  • team and business speak same language and can well understand each other;
  • teammates don't invent anything they just listen to the language of domain experts and automate the process;
  • with correctly crafted ubiquitous language new teammates can easily learn and understand project.

Ubiquitous language and BDD

We know that ubiquitous language are words that can be understood by domain experts and developers. However is there any tools or diagrams that can help us to model it? How should we write it and verify that everything is ok and have done according the specifications and meets business expectations?

One can try to write ubiquitous language in UML diagrams, however it is not a good option. UML is great for drawing connections between classed and various objects that are in play in our system. However ubiquitous language is not simple one to one match words to classes, it is much deeper to understand as we will see in next chapters and in tactical section of DDD. So what is the way to write our specifications and verify them if it is not a graphics or diagrams? We can see that our talks with domain experts look like short stories, where we have an actor which acts on the thing and gets some result. We highlight needed core concepts in words that are needed to write this stories. From this stories we obtain our domain contracts that should be fulfilled to model correct software. And there is a approach to write and verify such user stories. It is called Behavior Driven Development. We will not be fully covering in our chapters of what it is. You can find and learn details of Behavior Driven Development (or BDD) on your own. But it's worth to mention that in this approach all features that we want to do in our domain are written in user stories, almost those user stories that we saw above. In BDD user stories there is user - an actor that doing some things, the feature that should be fulfilled in this story and the result of such actions done by an actor.

Lets reconsider our e-commerce example, and think that we have done a lot of talks with domain experts to model things correctly, discovered other vital ubiquitous language like cart where customer can put his needed products. Now we can try to write a simple story that we obtained from our domain expert and crafted through ubiquitous language:

As a customer i want to buy several products
I put first product with 600 $ price to my cart
And then another one with 1000 $ price
When i go to checkout process
I should see that total number of products i want to by is 2
And my order amount is 1600 $

Another story can be about our purchasing domain area when we try to apply coupon to order

As a customer i want to activate special coupon on my order
I have a one-time coupon with 25 % discount
And my order amount is 1600 $ thus i can activate coupon
When i try to activate given coupon on order 
I expect my order price amount to be 1200 $
When i try to activate coupon once again
Then I cant do it due it was one-time coupon

###BDD and PHP

As we can see this short simple stories are written in our ubiquitous language they highlight our domain core concepts that are called contracts. We should fulfill those contracts to model software correctly. So, we found that it is great that there is an approach that helps us to highlight core concepts of our common language that domain experts and developers speaks. However how we can verify that those contracts are being satisfied, is there any software to do so? Yes, there is a software in php to do so. It is a port of well known Cucumber that is written in python and uses special language for such stories - Gherkin. In php we have a Behat that as was noted above is a port of Cucumber to php. It has almost same functionality and is good for our case. Lets see how we can write such stories in Gherkin language with Behat:

Feature: checkout process
    In order to buy products customer should be able to select several
    products and process his order

        Given As a customer i want to buy several products 
        And I put first product with 600 $ price to my cart 
        And then another one with 1000 $ price 
        When i go to checkout process 
        I should see that total number of products i want to by is 2
        And my order amount is 1600 $

The second story can be written in same manner. How to verify that this feature and scenario are valid? We can do it by simply running it, by default there will be generated empty feature with "pending" exceptions. We should add code that will complete our contracts and make scenario pass. However this is out of the scope of current chapter. For more information you can see Behat docs and examples.

You already may be know to Behat and its user stories, by writing scenarios for acceptance tests that model user behavior on the site pages. In this situation Behat is used with Mink, however this case has nothing to do with our current examples and DDD at all. We highlight domain contracts and business specifications that exists before any code can be written. In general our application can even have no any UI. So this situation should be clarified, since we don't write our software from the UI perspective, it is not a UI who defines our business specifications and expectations. The typical feature scenario in acceptance UI testing with Behat can look like the following:

Scenario: Show banner
  Given there is a banner:
    | title | Upper |
    | weight | 50  |
    | place | upper |
  And im on /index
  I should see upper banner
  When i change weight to 0
  And im on /index
  Then I shouldn't see upper banner


At the end of this chapter lets summarize what we have learned from it:

  • know what ubiquitous language is and what it is not;
  • know where we can take it from and how to craft it;
  • know that it should be crafted constantly;
  • saw how to get key concepts of our domain through ubiquitous language;
  • saw the benefit of applying ubiquitous language and what downsides are there if not doing so;
  • saw how to write core concepts of our ubiquitous language and verify them using existing software.

What is next?

In next chapter we will discuss another fundamental building brick of Strategic DDD design - Domain Models. We will see how they are connected to the ubiquitous language that we discussed in this chapter, and what is it.

Useful links


Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment