Please don't name your services after Greek gods

August 2, 2021

Often, the process of naming a software service or component starts with "I have a service that does x, what should I name it?", and ends with "Let's use the name of an ancient diety who is vaguely associated with x". For instance, a service responsible for user data might get named "Athena" (goddess of wisdom and knowledge), while a service that is responsible for notifications might get named "Hermes" (the herald of the gods).

Many teams and companies have adopted conventions that result in similarly "fun" names being used around the organization, from the names of constellations to birds to TV shows. There's even an entire website dedicated to the universe of all the naming schemes out there.

At best, these names can provide some vague hint about the purpose and function of the component. At worst, they sow confusion and ignorance. The most obvious example are new engineers who are just joining the team — the functions of services with vague names like "Sirius" or "Orion" is just another piece of knowledge that needs to be learned in an onboarding process that is likely already overwhelming.

However, vague service names can easily trip up even veteran engineers. As an organization grows, it will quickly become impossible to keep up with all of the new services that get spun up. This can lead to duplicate work: one team could easily spin up "Mercury", a SMS notification service, not knowing that another team in a different division has already created "Agni", that does the same thing. Had they called it the "SMS notification service" instead, the first service would have been more easily discovered and the extra development cost spared.

One could argue that there could be a perfectly good case to create two SMS notification services at a large organization. For instance, one could be used for updating users on the status of their orders, and another could be used for sending TFA tokens. However, there is no case for unknowingly creating two such services.

Using descriptive names ("user sessions", "accounts") offer further multiple benefits over arbitrary code names.

First off, service boundaries are considered and enforced. Calling a service "analytics" doesn't seem like a good idea, unless the intent is to handle all analytics use cases. If not, then something like "web analytics" might be better. No such consideration exists when calling your service "peacock". Furthermore, adding a new feature to a service (say, tracking email clickthroughs) might feel less natural if the service has a name that was specific to the initially defined boundary.

Secondly, components become more naturally discoverable. Sure, one could write a document with all of the services and libraries in an organization with descriptions of their functionality. However, formal documentation is only part of how knowledge gets disseminated throughout an organization. Overhearing "Mides" or "Janus" in the lunchroom or Slack channel is meaningless; hearing that the organization has a "rate limiter" or "geolocation" library is far more useful.

While software development can and should be fun, service/component naming shouldn't. As the number of services and components grows over time, so too will the number of vague, arbitrary and non-descriptive ones, unless the temptation for levity is kept in check. Engineers often obsess over how to name classes, functions and variables, with consideration for consistency, understability and long-term maintainability. Services and components are much larger and more important, and their names deserve even greater consideration.