The Domain versus the Domain Model

The domain represents the problem area you are working within. It is the firm reality of the situation. The domain model, on the other hand, is an abstraction of the problem domain, expressed as a code implementation that represents a view, not the reality, of the problem. This difference is highlighted in Figure 4.2. The usefulness of the domain model comes in its ability to represent complex logic and polices in the domain to solve business problems and not how well it reflects reality. It also exists in a more abstract space: in the language the team speaks and the diagrams it sketches. The model is built from the collaboration between the development team and the business experts. The model contains only what is relevant to solve problems in the context of the application being created. It needs to constantly evolve with the business to keep itself useful and valid. The domain model only exists to help us solve problems; in order to be effective it needs to have clarity and be free of technical complexities. This way both the business and development teams can collaborate on its design.

The Analysis Model

Also sometimes known as a business model, an analysis model is a collection of artifacts that describe the model of a system. These artifacts can be anything from cigarette packet sketches to informal UML. The analysis model exists to help both the development teams and business users to understand the problem domain; it is not a blueprint for the technical implementation.

The Code Model

DDD doesn’t advocate the removal of the analysis model. Far from it, because there is much value to be gained from a model that describes the system. Instead, DDD emphasizes the need to keep the code model, the implementation, in close synergy with the analysis model, the design. This synergy is achieved by ensuring both models are described and share the UL, as shown in Figure 4.3. The utopia is a single model that has value in both implementation and design. To achieve this, it is crucial to keep the code model clean of technical concerns and focused on the domain. In turn, it is important to have an analysis model that can be implemented—not too abstract or high level to be of any use.

The Code Model Is the Primary Expression of the Domain Model

The code model is the realization of the analysis model; it validates the assumptions of the business and quickly highlights any inconsistencies with the analysis model. If, during the creation of the code model, issues are found and logic doesn’t seem to fit, the development team should work with the domain experts to resolve these problems. This update to the code model is reflected in the analysis model by making changes to work flow and polices that may not have exposed issues before. Likewise, any changes from a business perspective need to be reflected in the code model. The code and business models are kept in synergy. The code is the model; the code is the truth.

The Challenges with Upfront Design

Historically, the capturing of requirements for software systems was seen as an activity that could occur long before coding was due to start. Business experts would talk to business analysts, who in turn would talk to architects, who would produce an analysis model based on all the information from the problem domain. This analysis model would then be handed over to the developers, along with wireframes and work flow diagrams, so they could build the system

As developers start to implement the analysis model in code, they often find a mismatch between the high-level artifacts produced by architects and the reality of building the system. However, at this stage there is often no feedback loop for developers to talk to the business and architects, so the analysis model can be updated and their input enacted. Instead, the developers diverge from the analysis model, and their implementation often overlooks important and descriptive domain terms and concepts that would have provided deeper insight and understanding of the domain.

As the development team further evolves away from the analysis model, it becomes less and less useful. Crucial insight into the model is lost as the development team focuses on abstracting technical concerns instead of business concepts. In the end the job gets done, but the code bears no reflection to the original analysis model. The business still believes the original analysis models are correct and is unaware of the alterations within the code model.

Figure 4.4 shows how the analysis and code models can diverge from each other if the development team is not involved in domain knowledge crunching.

The problem is revealed when later enhancements to the codebase are difficult to implement. The difficulties are due to the business experts and developers having different models of the business. The code doesn’t have a synergy with the business processes and is not rich in domain knowledge.

Team Modeling

DDD suggests a more collaborative method of capturing system requirements and understanding existing work flow. Emphasis is placed on the entire team, with business experts and architects (as long as they code) having discussions around the problem space. Discussions can include any documentation or legacy code that is related to the system in question. The idea behind the collaborative knowledge-crunching sessions is for the developers, testers, business analysts, architects, and business experts to work as a unified team. This enables the developers and testers to learn about the meaning behind domain terms, and understand complex logic in the problem area. It also enables business experts to experience the modeling techniques employed. With an understanding of modeling, business experts will themselves be able to model and validate designs with the development team.

The sharing of information enables business experts to contribute to the software design, and provides a deeper insight and understanding of the domain to the development team. After a period of time, developers and business experts will discover the relevant information to build an initial model of a problem domain. This initial model is put to the test by using domain scenarios: real problems of the domain to validate its usefulness. Modeling out loud, using the terms and language of the model, can also help to validate early designs.

The important aspect of modeling together is the constant feedback the development team gets from the business experts. This leads to the discovery of important concepts and allows the team to understand what is not important and can be excluded from the model. Breakthroughs in sessions are manifested as simple abstractions that clarify complex domain concepts and lead to a more expressive model.

The model is then expressed in code and the team, along with business experts, can gain fast feedback with early versions of software. Feedback in turn fuels deeper insight, which can be reflected in the code and analysis models, as highlighted in Figure 4.5.

During each iteration, the development team members may come across parts of the model that they thought were useful and could solve a problem but during implementation had to change. This knowledge is fed back to the business experts for clarification and to refine their own understanding of the problem domain. In this process, the code model and analysis model are one, and a change in one will result in a change to the other.

Figure 4.6 shows how the analysis and code model are in synergy and evolve as one during the creation of a product.

A Language Will Outlive Your 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.

The Language of the Business

I recently went curtain shopping with my wife. Pleated, hang length, interlining—these were all terms that meant something specific in the domain of curtain makers. Employees in the shop could spend hours describing what they wanted, but that could lead to ambiguity in meaning. But because the employees use terms in the domain of the curtain shop, conversations are kept short and concise, and everybody who understands the domain understands their meanings.

It’s the same with carpenters, financial traders, the military, and nearly every domain you can imagine. Each has terms and concepts that mean something very particular to them. A secret language enables complex topics to be covered in concise and meaningful dialogue without the need for confusing babble. It’s vital for a development team to understand and collaborate on this language, known as the ubiquitous language (UL). The UL’s terms and concepts are used when communicating with team members, including domain experts. They’re also used to name classes, methods, and namespaces in the codebase.

Translation between the Developers and the Business

The business language is a rich dialect with highly descriptive and insightful terminology. However, if the development team doesn’t engage with domain experts to fully understand the language and use it within the code implementation, much of its benefit is lost. Developers instead create their own language and set of abstractions for a problem domain. Without a shared model and UL, effective communication between the development team and domain experts is a challenge and requires some form of translation. Translation from domain concepts to technical concepts can be time consuming and error prone. Vital domain insights can be lost when the team implementing the code is using a different model than that of the domain expert. Furthermore, lengthy and convoluted communication is required to explain problems that the team faces in a software implementation that could be solved easily with a better understanding of the problem domain and a more efficient way of communicating.

Figure 4.7 shows how a different model in the minds of a developer can make communication with the domain expert problematic. In the code, the developer is focused on technical abstractions, design patterns, and design principles, whereas the domain expert is focused on business process and work flow.

Developers should think in domain terms and concepts, not technical terms, to avoid the need to translate from business jargon into technical jargon. If the development team makes a mistake when translating complex logic and work flow, the chance of creating a bug in code significantly increases.

Carving Out a Language by Working with Concrete Examples

As mentioned in Chapter 2, “Distilling the Problem Domain,” to better understand the domain you’re in, it’s a good idea to take specific examples of domain behavior. Concrete examples of real scenarios help to cement processes and concepts within the domain. However, it’s important to reveal the intention of the business process and not the implementation. Talk only in business terms; don’t get technical.

In the following dialogue, a business user is describing the process of customers at an e-commerce site requesting a replacement for an order that wasn’t delivered:

When a customer doesn’t receive her goods, she can request a new order for free. She logs into her account and clicks on the I Have Not Received My Items button. If she has already been flagged as having received a free order, she can’t get another one without speaking to customer service. Otherwise, we will send her a free order and update the database to show that this customer has already claimed for a lost item. We will then contact the courier to see if we can claim back the cost of the lost order.

You will notice in the description that the business user is not focusing on the business process, but rather the implementation concerns. The following sentence gives no value or insight into the domain or business process:

She logs into her account and clicks on the I Have Not Received My Items button.

In the next sentence, the business user is already second-guessing how you will implement the business policy. Some experts may have experience with databases and may go as far as suggesting data schemas. Again, this gives the team no deep understanding of the domain:

If she has already been flagged as having received a free order, she can’t get another one without speaking to customer service.

From this set of requirements, a team not interested in the domain may simply implement what it is told and end up with a poor model that doesn’t reflect the concepts and policies of the domain. The impact of this could be a misunderstanding of what “flagging the customer” means; it may mean more than simply a tick in a database column and perhaps the catalyst for the start of a separate business work flow. Without understanding the domain and the intent of a feature, the developers won’t appreciate the repercussions of just implementing what they are told.

Teach Your Domain Experts to Focus on the Problem and Not Jump to a Solution

Training and collaboration will help business people focus on the process rather than the implementation and the problem space rather than the solution space. Next, the previous requirements statement has been rewritten using the language of the domain. It focuses on the business and its processes:

If you have not received an order, you can submit an undelivered order notification. If this is your first claim, a replacement order is created. If you have made a claim before, your claim case is opened and assigned to a customer service representative, who will investigate the claim. In all cases, a lost mail compensation case is opened and sent to the courier with details of the consignment that was undelivered.

In this description, you have discovered many important domain concepts that were missing before. The rewritten prose introduces some terms into the UL, and the terminology of the domain has been made crystal clear. In fact, the second description doesn’t even contain the customer concept; instead, it focuses only on terms that are directly related to the process.

Remember: domain experts have no, or limited, understanding of technical terminology. Keep examples focused on the business, and if domain experts are trying to help you by jumping to implementation details, just gently remind them to focus on the what and the why of a system and ask them to leave the how up to you.

Best Practices for Shaping the Language

The following best practices can help to shape your UL.

• Ensure that you have linguistic consistency. If you are using a term in code that the domain expert doesn’t say, you need to check it with her. It could be that you have found a concept that was required, so it needs to be added to the UL and understood by the domain expert. Alternatively, maybe you misunderstood something that the domain expert said; therefore, you should rectify the code with the correct term.
• Create a glossary of domain terms with the domain expert to avoid confusion and to help make concepts explicit.
• Ensure that you use one word for a specific concept. Don’t let the domain expert or developers have two words for something because this can lead to confusion, or there might be two concepts with different contexts.
• Stay away from overloaded terms like policy, service, or manager. Be explicit even if it means being wordy.
• Don’t use terms that have a specific meaning in software development, such as design pattern names, because developers may assume its implementation rather than behavior.
• Naming is very important. Validate your code design by speaking to your business users about classes. Would a business user understand “Query sent to the cache with, users matched using regex to determine if they get discount”. Does your code and concepts make sense when you say them aloud? If not ask your domain expert on how they would name concepts.
• Name exceptions in terms of the UL.
• Don’t use the name of a design pattern within your domain model. What does a decorator mean to a business user? Would they understand the role of a factory? Perhaps your business already has the concept of an adapter; the Gang of Four design pattern could confuse them.
• The UL should be visible everywhere, from namespaces to classes, and from properties to method names. Use the language to drive the design of your code.
• As you gain a deeper understanding of the domain you are working in, your UL will evolve. Refactor your code to embrace the evolution by using more intention-revealing method names. If you find a grouping of complex logic starting to form, talk through what the code is doing with your domain expert and see if you can define a domain concept for it. If you find one, separate the logical grouping of code into a specification or policy class.

Don’t Let the Truth Get in the Way of a Good Model

A common misunderstanding is that a domain model should match reality; in fact, you should not look to model real life at all but rather model useful abstractions within the problem domain. Look for commonalities and variations within the problem domain. Understand which are likely to change and are considered complex. Use this information to build your model. It will be far more useful than identifying nouns and verbs based on the world of the problem domain. Most importantly model only what is needed to meet the need of the business case scenario.

A domain model is not a model of real life; it is a system of abstractions on reality, an interpretation that only includes aspects of the problem domain that are prevalent to solving specific business use cases. A domain model should exclude any irrelevant details of a domain that do not serve to solve problems. The London Tube map shown in Figure 4.8 was designed to solve a problem. It doesn’t reflect real life. It isn’t useful for calculating distances between landmarks in London, but it is useful for traveling on the underground. It’s simple and effective within the context that it was designed for.

Because it’s not concerned with modeling real life, the domain model cannot be deemed as being wrong or right. Rather, it should be viewed as useful or not for the given problem it is being used to solve.

Creating an effective domain model is fundamental to DDD. It is the artifact of knowledge crunching and sharing, design insight, and breakthroughs. Having a useful model that is rich in the UL is the key to meeting business objectives in the problem domain. Creating a useful domain model is hard and takes lots of exploration, experimentation, collaboration, and learning.

Model Only What Is Relevant

The domain model exists for one reason: to serve the application under development. Remember to be selective when creating your domain models; you don’t have to include everything. Businesses are big and complex with a lot going on. Trying to create that world within a single model would be at best foolish and at worst extremely time consuming and rather pointless. Needless to say, it would be a maintenance nightmare. If you are modeling a large system, break it down to more manageable chunks by clearly sectioning off parts of the model.

Try not to model real relationships; instead, define associations (meaningful connections) in terms of invariants and rules in the system. In real life, a customer has both a credit history and a contact e-mail address, but how often would you come across a rule requiring you to have a good credit history and an e-mail address starting with “A” to be able to purchase an item? Instead, group behavior and data to satisfy the needs of the problem domain rather than what you think might belong together. Remember that you are producing a model to fulfill the needs of a business use case (or set of business use cases), not trying to model real life.

To keep your domain model relevant and focused, you should constantly challenge the model you create against new scenarios and validate your understanding with domain experts. Remove any behavior that is no longer relevant to avoid noise.

Domain Models Are Temporarily Useful

A domain model needs to be constantly refined to continually be useful. A domain model is only ever temporarily useful for a given iteration and set of use cases. Future use cases or changes to the business may render the model useless. The domain model represents an implementation of the shared language that is applicable for only that moment in time. It is with this understanding that developers should not be too attached to an elegant model. They need to be willing to rip up and start again if the model becomes irrelevant.

Be Explicit with Terminology

Being able to communicate effectively is the most important skill for solving problems. A developer’s purpose is not to code; it’s to solve problems. That’s why it’s vital to talk to the business you are working for in a language without ambiguity or need of translation. By removing linguistic barriers, domain experts and the development team are free to collaborate, explore, and experiment with designs for a useful model. Technical implementations can then be expressed using the same UL, and any design insights can then be fed back to domain experts for validation without need for translation and loss of meaning.

Limit Your Abstractions

Introduce abstractions for commonality only, and even then try and avoid them. Abstractions come at a cost. It is far better to be explicit than worry about not repeating yourself as trying to tie loosely related concepts under a super class can cause problems with code maintenance.

An abstract class or an interface should represent an idea or a concept in your domain. It is really important to limit abstractions in your code base and only create them for concepts in your domain that have variations. Don’t seek to abstract every domain concern. If it’s not a variation of a concept then keep it concrete and only abstract if, and when, you create a variation of it. Remember it is always better to be explicit rather than hiding an important domain concept behind layers of needless abstraction.

So when should you abstract? Take the example of traveling to work. The abstract concept would be to commute whereas walking, taking the train, or driving is a variation of that concept; i.e., the concrete implementation. If there were no variation in traveling to work (i.e., we all drove) we would not need to introduce an abstract concept such as commuting.

Implement the Model in Code Early and Often

It is vitally important to test your design in code against domain scenarios to ensure your white board thinking can work as well as discovering any technical constraints that require an alteration or compromises to the model. Technical implementations will reveal any problems with the design and will help cement your understanding of a problem domain.

Don’t Stop at the First Good Idea

Only stop modelling when you have run out of ideas and not when you get the first good idea. Once you have a useful model start again. Challenge yourself to create a model in a different way, experiment with your thinking and design skills. Try to solve the problem with a completely different model. If you don’t get it right the first time, refactor to a better solution. Constantly refactor to your understanding of the problem domain to produce a more express model. Models will change with more knowledge.

Remember a model is only useful for a moment in time; don’t get attached to elegant designs. Rip up parts of your model that are no longer useful, and be willing to change when new use cases and scenarios are thrown at your design.

If It’s Not Worth the Effort Don’t Try and Model It

If you have a particularly nasty and complex edge case that is in an area of the system that is not core then you should think about making it a manual process. Not handling edge cases and making them an explicit manual process instead can save valuable time and give you more resources to work on the core domain. Humans and manual processes are great at edge cases and can often make decisions based on data that would take a considerable amount of time to replicate.

Focus on the Core Domain

The core domain of your application is why it is being built rather than bought. It is what your stakeholders are most passionate about, and where you can have interesting conversations and valuable knowledge-crunching sessions. This is the area where your UL gives you the most value, and demands your focus. Try not to create a rich language for your entire domain because many of your supporting and generic domains do not require one and are a waste of effort. Focus your efforts on what gives you value. Try not to create a UL for everything. Areas and subdomains that are not complex will not benefit from a UL, so don’t spread yourself too thin. A core domain is small; focus on it. Creating a UL is costly.