When we start working on a new system, we need to learn a lot. We discussed the paradox of ignorance in Chapter 1, Why Domain-Driven Design, and you might remember that the highest level of ignorance and thereby the lowest level of knowledge if when we make a lot of decisions about the future system.

But not only we suffer the lack of knowledge about the business domain we are trying to solve problems for, but we are also forced to work in an environment with high-level of ambiguity. Before we learn the domain language deeper, understanding is often based on assumptions.

Imagine a situation when you come to a meeting with domain experts in the beginning of the project. They try to explain their problem and you slowly begin to study their language and at some point, you think you got the idea and more or less know what to do. Here it is important to remember what we were going through in the previous chapter when we discussed cognitive biases and their influence on decision making. The first and the most obvious risk is that what you see is all there is (WYSIATI) or availability heuristic. You apply your limited knowledge to past experiences and then get the feeling of understanding. At this point, we usually are asked to make estimates and logically we fail, since biases play a trick on our minds and give the illusion of understanding.

At such meetings, we often agree on something. Then, everyone leaves the room to meet again and maybe discussing some specifications or even prototypes after a couple of weeks. Time passes by, and here we are still in the same room, and no one is pleased, since to our mutual dissatisfaction we find out that when we agreed, we agreed on completely different things. Everyone has had a picture in mind, and all those pictures were different.

People spend hours arguing about things they thought are different but in fact are the same. People also agree on something that they do not share a common understanding about, and this never works well.

To fix this, we need to remove assumptions. We need to make implicit things explicit.

Look at this sample form from a real-life HR-management system. Here an employee can submit a sick leave as follows:

 

Here we see a typical structure, which is created by a programmer. We could even imagine a SQL table where the data entered to this form gets stored. It most probably has the StartDate, EndDate, and HalfDay columns and the employee id. Notice that there is a Save button here too, which is very common to find in forms like this.

But despite the fact this form might look okay, let us think a little bit more about what we see here. After spending a bit of time analyzing this form, we could see the following issues:

1. The Start date is ambiguous. It might be the date when sick leave is registered, or it might also be the date when the employee did not come to work because he/she got sick.
2. The End date is even more ambiguous because it might represent the last day of the sick leave, or the day when the employee came back to work.
3. The Half day might apply to both of those fields, but there is no clear indication when it means.
4. Finally, the Save button gives us no clue what shall happen next. There might be just a record in some table created, and we need to tell someone to look at it, or there might be an approval process that gets started automatically. Does employee need to call or send an email to the line manager after filling out this form?

As you can see, even in such a small form with two fields, one checkbox, and two buttons, there are many things that are implicit. If we imagine the code behind this form, all those implicit and ambiguous concepts could definitely be found there as well. I already mentioned a table, which has columns that represent those fields in the form. All properties in the domain model classes, data model objects, and other code artifacts are equally implicit. Everything there demands explanation like this date actually means the day when an employee came back to work and without such explanation, things like reports could be just plain wrong.

Compare it with another example, also taken from a real-life HR-management system, made by a competitor:

In this form, fields have much more sense for regular people, which don't need to solve puzzles or read the help in order to understand what to enter to these fields. Things that were made implicit in the first sample, are clearly explicit here. Everything, from naming individual fields, to calls for actions, has a better meaning. We could also imagine that behind this form we can find code like this:

SickLeaveApplication.Handle(new SendSickLeaveForApproval
{
    EmployeeId = context.User.EmployeeId,
    DateRegistered = request.DateRegistered,
    FirstDayNotAtWork = request.FirstDayNotAtWork,
    LeftDuringWorkday = request.LeftDuringWorkday,
    CameBackToWork = request.CameBackToWork,
    CameBackAfterLunch = request.CameBackAfterLunch
});

This code expresses the same meaning and terminology as the user interface. So not only the end user will have an easy time filling out this form, but also a fellow developer would be happy reading this code, where the intent is clearly expressed and all concepts are explicit.

Another aspect of making implicit explicit is to create domain concepts visible in the code. The preceding example is a correct example, as the SendSickLeaveForApproval command exhibits a precise domain concept in the code.