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?
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.