Domain-driven design includes the idea of a “ubiquitous language” where the engineers and the domain experts and the product owners come together and agree on terminology for all the domain concepts, and the project then uses that terminology everywhere.
But on the projects I’ve been involved with, much more common is a situation where the requirements docs mostly use one term but sometimes use a different name for the same thing because the docs were worked on by two people who disagreed on the terms, the designers decide they don’t like how the words look so the UI calls the concept something else, the database developer reverses the term’s word order to fit their personally-preferred schema naming conventions, the API designer invents a compound name that includes both the UI and the database names, and so on. (I only barely exaggerate.) Which names map to which other names becomes tribal knowledge that’s usually not written down anywhere.
This kind of thing bugs me a lot, but I seem to be in the minority. I recognize that it makes very little functional difference, but it just feels sloppy to me and I don’t like having to remember multiple names for things. I will usually advocate for renaming things in the code for consistency, and other people on the team will almost always agree that it’s a good idea and will happily accept my PRs, but I’m usually the only one taking the initiative.
So, my question to you fine folks: am I wrong to care much about this? Do you think using consistent names for domain concepts across the board actually makes a meaningful difference in terms of code maintainability and discoverability? Or is the effort required to keep the names consistent over time actually greater than the mental overhead of working with the inconsistent names?
I build software that is used by nearly all engineers in our company. We own hundreds of web applications and websites. We’ve grown by acquisition of smaller companies, and we have an extremely heterogenous environment.
25 years ago, I started my career as a web designer. Today, I’m a Principal Cloud and Platform Engineer. Still to this day, I regularly leverage lessons when building tech that I learned from the world of UX.
“Design is not how it looks. Design is how it works.” — Steve Jobs
Naming consistency helps to reduce the mental friction that people have when learning how something works. For example, one my projects is a suite of Terraform modules that are designed as building blocks which cover all of the fundamental pieces of any app’s stack. We have designed these 20-ish modules to work well standalone, as well as when used together. Certain patterns are the same across the board.
(1) We strongly favor dependency injection, and limit the use of ternary statements. In the world of Terraform, this is via variables or a .tfvars file. Everyone knows that this is how it works, so it reduces the mental friction when adopting a new/additional module.
(2) Variable names which do the same thing are named identically across all modules. Their descriptions are identical. For example,
tags = [k:v]works exactly the same way across all modules, and people don’t have to think about it.(3) Modules have a naming pattern. Among other things, they begin with the name of the service that the module talks to. (If we find that we’re talking to multiple services, we need to break the module down into smaller chunks.) So
aws-ornewrelic-ordatadog-orgithub-orpagerduty-are all examples.This overall “design” has not only helped reduce mental friction and made the modules easier to understand and use, but it also makes them easier to manage across hundreds of repositories supporting hundreds of apps. Collaboration, cooperation, and communication are all improved as a result. And if something is difficult to understand, then it means that we screwed up. We need to do a better job listening to the app-engineering teams and SREs who support them to streamline and clarify as much as possible.
“Customers” come in all sorts of shapes and forms.