Normally I’m quite a calm chap but I get quite grumpy when developers want to model the business domain using technical language. I believe in using “ubiquitous language” and that means using business language to model the business domain.

Why ubiquitous language

We need ubiquitous language within the team. Seems obvious to me, and is a principal of BDD according to Aslak Hellesøy, but it is not obvious to all. Ubiquitous language means the business and the development team use the same terms for the same things. The business uses those terms, so the code uses those terms, and so does the Gherkin scenarios and the user interface. Everything. That is what makes it ubiquitous. And if we’re going to use one set of terms then we must use the terms used by the business. We are, after all, modelling their domain with our software.

This is all about reducing confusion and translation time. The point of Cucumber and Specification by Example / BDD is to collaboratively define the business rules and ultimately the system behaviour in general. If a developer is talking to a user it makes everything a lot easier if both are using the same language, and neither is having to do a mental translation with every sentence.

Example of non-aligned language

I thought I’d illustrate the confusion I’m trying to avoid with a real example. My development team were working on an application to plan News. Roughly speaking this is about putting news stories into a variety of news diaries. The developers said, “Great, we understand that. This is a many to many relationship between Diary and Story.” Here’s the entity relationship diagram for that:

The developers then dug a bit deeper and discovered that actually there was some data to collect about the relationship. The planners for different diaries assign a different priority to the different Stories. The developers said, “Got it. We’ll insert a many-to-many resolver in there called DiaryEntry and attach a priority field to it”. The data model then became:

Classic Computer Science 101. Many-to-many gets replaced by a link entity. They might have called the link DiaryStoryLink but clearly had some insight and called it DiaryEntry instead. After all, diary entries go in diaries.

Although this model made sense to the developers it did not resonate with the business. The journalists used a different language. And even worse, two of the terms used by the developers meant something completely different to the journalists. This is the way the journalists saw the world.

Diary: Developers and business were agreed on this. A diary was the list of interesting stuff for the day. Agreement ceased after that.

Story: The developers thought the journalists wrote stories and hence the news planners planned stories. But it wasn’t true. To the journalists a story was a big thing. Huge and hence a bit wooly. It might be a specific event (“Chilean earthquake”) or just a concept (“Environment”). Stories are such a big and encompassing things that the journalists advised against modelling them.

DiaryEntry: This is where the big problem was. The developers thought DiaryEntry was a link between Diary and Story. But to the journalists a DiaryEntry is the part of a story that is being explored and is literally the thing that goes in the diary. This is true for physical diaries so, to them, also true for virtual diaries. Obvious really. The DiaryEntry wasn’t necessarily all of the story, it was the particular angle the journalist was going to take on the Story. A Diary might have several of DiaryEntries about a single Story on the same day. For example the “Egypt” story might spawn DiaryEntries for “Extremism”, “Military Rule” “Women’s rights”, and “Environment”. In addition the same DiaryEntry could appear in different Diaries with different priorities, which leads us to the last entity…

Interest: For the journalists the presence of a DiaryEntry in a Diary was an Interest. This was highlighted by the language they used when talking to each other. For example: “The mid east diary is interested in that entry on Egyptian Extremism.” “How interested?” “Very interested.” What the developers saw as a Priority attribute of a DiaryEntry about a Story the journalists saw as a Level of Interest in a DiaryEntry.

If I had let the developers use their terms for the entities their computer science lecturers might have been pleased and they would have been modelling a domain. However they would not have been modelling the domain of their users, the journalists. So the developers refactored their code and tests to reflect the language used by the business.

This post is part of a series on Specification by Example.

References

Hellesøy. A. (2011, 5 Oct). The training wheels came off. Author