Lost in Translation? Build a Project Dictionary

“There are only two hard things in Computer Science: cache invalidation and naming things.”

Phil Karlton

As reluctant product managers, we don’t really worry about cache invalidation, but establishing a shared understanding between us and the development team is a prime responsibility.

In order for application source code to be self-explanatory, it needs to be modeled on the real world. So in the source code of an ecommerce store application for example, you want to see object names such as article, shopping_cart, order, receipt etcetera.

That may sound obvious, but it is not.

Let’s take the shopping cart as an example.

How would you call the contents of a shopping cart?

An online shopping cart with a circle around one (arbitrary) item, and text asking ‘What should this thing be called?’

A store owner might call them articles.

But a developer would disagree. They would say, an article has a name, a catalog_number and a price. The items in a shopping cart have a quantity and an amount. We’re talking about two different things!

So here, we need to agree on a new definition, let’s say, a shopping_cart_item.

This example illustrates how quickly the vocabularies of domain experts and developers can diverge. It is not hard to imagine what happens in larger and more complex projects.

As the domain language evolves, the source code needs to be kept up to date, which can be hard in practice. Developers might resist making changes in object, function and method names because it may seem trivial compared to troubleshooting, refactoring, adding features or writing tests.

However it is important for product teams to be on top of keeping terminology in documentation and source code in sync. If they don’t, it will become more difficult to maintain the application, and the costs of maintenance go up.

Further reading

Stay informed of new posts?

Sign up below and you will receive a weekly digest of new posts.

If you change your mind, you can unsubscribe at any time. You will not be spammed, and we will keep your email address private.

Article index