Names should be descriptive, not cute

Names should be descriptive, not cute
Photo by Jeffery Ho / Unsplash
‘There are only two hard things in Computer Science: cache invalidation and naming things.’
- Phil Karlton

Mixmaster, Broadside, Windcharger, Ransack, Ramjet, Wheeljack, Skyfire, Slingshot and Wideload. Those were project names I had to deal with in my previous role. Some of those projects were backend services, some libraries and some were for a frontend.

"Why is there a RansackRunner in Windcharger that actually runs Ramjet?
- Some engineer

Unlike the author of "Names should be cute, not descriptive" I believe the opposite to be true.

The main arguments from the linked article can be summarized as:

  • Projects change and names may no longer fully reflect the responsibility of the project
  • Descriptive names are hard to say and remember and are not "fun"

Names serve a major purpose: They help everyone involved in a project understand what is being talked about. In a company with many projects in can quickly get confusing when you have tens of "cute" project names thrown around on a daily basis. Almost every month I would have to spend time in meetings explaining the difference between two similar sounding "cute" project names and reminding everyone what those projects actually did. Additionally, while the engineers would often refer to the projects by their cute name, the PMs would not bother remembering the names and instead talk about "the backend" and "the frontend" which caused significant friction and confusion on both sides.

The moment we switched to more descriptive names this changed. By following the Domain Driven Design's "Ubiquitous Language" between our different functions we were able to find names that were easy to remember, specific enough for our business context but generic enough not to limit the projects' growth.

Not only was communication easier with the descriptive project names it also helped onboarding new engineers and PMs who now didn't have to spend the first few weeks on the job producing their version of an up to date glossary to map codenames to "what does this thing do".  

Projects would still evolve and the names would eventually longer fully describe the responsibility of the underlying service or library. When this happened there were three options:

  • alter the name to once again fully capture the responsibility of our project
  • refactor the project and split it up
  • keep the name as it was still "good enough"

Renaming projects is often harder than finding the name in the first place because project names percolate into many places such as environment variables, class names and functions. For this reason we never actually renamed a project, we simply phased it our over time and replaced it with a project with a more descriptive name.

It's rare and speaks of bad decision making when a project suddenly does a 180 and somehow no longer matches any of the original intent embodied by its name. When you hide behind cute project names it's easy to let something like this slip, but when you have a descriptive name it allows you to catch problems like this early on.

Sometimes though the name is simply still accurate enough and an argument could be made that feature X is close enough in context for it end up in the specific project. This is the case when a feature is merely extending the original project and doesn't introduce something completely new.

There may be a middle ground to all of this. If you are a company with a massive monolithic application then the name will probably not matter too much. It will be fine to give it a "cutesy" name. The moment you expand to multiple codebases or even microservices I strongly suggest sprinkling some descriptiveness into the name. It's entirely valid to combine cute and descriptive and produce a name like "godzilla-auth-service".

The world is boring enough as is. Let's add more whimsy and cuteness through our service and project names.

The world is pretty ok. Let's be kind to each other and use descriptive names and not make work harder than it needs to be.