Cameron Hotchkies


  • Coding


  • development
  • project-naming

One day you find yourself setting up a new greenfield project. Your team needs a service that connects to an upstream account management system to get the active subscription status of a user. Since it only changes daily, to reduce load, the subscription status will be cached in this service. You now are faced with your first decision. Do you name this customer-subscription-cache? Or do you name it yard-lobster?

Defending the Yard Lobster

An argument for the customer-subscription-cache name is that it describes what the service does. Which it does, for about 3 minutes. Two things happen in real life though. The first is that features and requirements change. We may need to add some special case decisions (we always do) and the cache part of the name is now a partial lie. The second is that people organizationally will never refer to it as the customer-subscription-cache, but instead as The CSC. This means you can no longer have a custom-script-compiler or a concurrent-shell-channel.

Eventually, people will refer to The CSC and confuse it with entirely unrelated services because they have no idea what the acronym expands to, but were afraid to ask. Instead, if the name of the service is weird and non-descriptive, like yard-lobster, people feel more comfortable asking what it does until they are sure. In the same vein, the first sentence in the project README is forced to identify what the purpose of the service is. Not compilation instructions, not generic templates, real intention statements.

The Next Generation

As code evolves, it’s entirely common for services to be replaced or combined. This is another great reason for strange names. When one service replaces an older one, there is less ambiguity between the old and the new. Was it customer-subscription-cache or client-subscription-service? Did it merge with the subscription-feature-service? With strange names, it’s a lot clearer what service is going away. They are easier to disambiguate as they evolve, as we have a tendency to anthropomorphize projects that have weird names.

Lean in to the personalities

A positive side effect of falsely assigning personalities to software is that we stop assigning the personalities of the developers. It is common for engineering team members to define communication flow by stating:

  • Alice receives the request and forwards it to Bob
  • Bob adds supplementary data and sends logging data to Charlie
  • Charlie is throwing exceptions all over the place

This is not good for general team health. People get defensive about the systems they work on, since their persona has been associated with it. In the above example, there’s a subtle statement that the instability is somehow Charlie’s fault, even though they only joined the project two weeks ago and inherited this problem service. Instead, the same statement of flow is restated as:

  • Velvet-Tractor receives the request and forwards it to Stove-Nickel
  • Stove-Nickel adds the supplementary data and sends logging data to Doll-Hammer
  • Doll-Hammer is throwing exceptions all over the place

Wait, why is Doll-Hammer acting up again? Charlie, do you need help figuring out why that system is acting strangely?

A note on name sources

A common source for non-descriptive names tends to be pop culture references, including movie quotes or characters. I would highly recommend not using those. The first reason is that a joke from a movie that came out in the 1970s is nowhere near as funny now as you think it is. The second being that as culture evolves, some movies, quotes, and even fanbases become problematic. Just avoid that and go with random word generators. You will get far more interesting results.

Help the people you haven’t met yet

While it may seem more helpful to give descriptive names up front, as organizations grow and leave swaths of archived and abandoned projects the chances of collisions grow. As a new person entering an organization, there are usually blogs, wikis, and source control that compete as sources of definitive information. Since it is all but guaranteed that the search functions for all of these are terrible, trying to determine which authentication-client variant is the one that applies to you, as a new developer, is borderline impossible. So much time is wasted reading about a totally unrelated project. Strange longer names ensure that poor search engines are able to key in on the correct project. Also, forcing people to ask for clarity is a good thing. Just try to make sure the names are over five characters to ensure that overzealous search code will not ignore it.