Basic Terminology is NOT trivial

2017-09-27

The first time I read “Domain Driven Design”, there was something that resonated with me right away: the concept of the Ubiquitous Language.

Shared Terminology

The Ubiquitous Language is a term coined by Eric Evans on his DDD book which boils down to “a set of terms and ideas shared between all members of the project and describe the domain model”.

I’d like to emphasize here the “shared between all members of the project” part. This is IMO the most important thing on a team. All components of the team must have the same name for the same things so to prevent confusion both when talking to each other as well when coding.

Wrong Terminology causes Problems

Scenario

system A sends data to system B through a link system

System A generates some data that will be consumed by the “Link System”. The latest will in turn work on the data and eventually send a different kind of data to “System B”.

Now let’s say that both the A and the Link system call their outgoing objects simply outPackage. Let’s also assume that due to some business decisions these two systems were implemented in parallel by two different teams. The system works as expected but eventually someone needs something changed or a bug arises.

The problem arises

Let’s suppose that Johnny New B. is the new programmer in the team. Someone assigned him the issue to fix and that was basically it and said he could use the opportunity to “explore the codebase” too. He does his best and find the bug which was on the output generation of the link system. He understood how that works and was feeling great about himself.

A while later John receives another issue to be fixed. This one is on the output generation of System A. He goes in and “oh what a happy day” they are also using the outPackage!!! But wait?! This is not the same… why is it using this method? Why is it being passed like that?

Now John has a clash of his mental models and he doesn’t know which one is right and which one is wrong. Although eventually he might figure it out he will need to keep a mental note of this confusion so he won’t fall in that trap again. In this case some rethinking of his system understanding was necessary. We should avoid that.

This could all be avoided if he was presented with the overview AND if the teams had a shared Terminology instead of homebrewing their own among the teams.

Accidents Happen

Of course sometimes the terminology gets mixed due to a well intention person that didn’t know the term was already in use or some other similar reason. But there is where the code reviews and the sync meetings come in play.

These are in place to try and minimize or avoid all together such mistakes.

What can we do?

Here is my take on this:

1) Keep a wiki of the basic terminology

There is not much to it: use a wiki of some kind to maintain a list of the terminology which was agreed between business and developers together with a simplified explanation of the term itself. If there is material on the term already link to it, but still do provide an one-liner explanation.

If necessary add a page with a list of acronyms and abbreviations, because you and me both know that the industry has A LOT of them and probably your company came up with some others to go along

2) Make sure people know where to find this information

If you have an index add to it and make sure people know where the index is at. Also add it to a “Newcomers” page, and if you don’t have that then add it!

3) Encourage people to correct and use the terms

If you see someone using a term incorrectly on code or speech, gently correct that person and offer an explanation of how the term is being used wrong if that is the case. But please, don’t be sarcastic or go crazy on the person because of the mistake. It is already a pretty bad feeling making the mistake on something you don’t feel 100% familiarized with. You don’t need someone making fun or being angry at you on top of it.

Conclusion

Use and share a common set of terms. Yes it maybe a bit time consuming to keep taking care of those wiki pages, but it is worth it and everyone gains from it.

There are other points that can help a person to do a better job and we will discuss them in another post. For now just remember: