I've previously written that project names should be cute, not descriptive. That post talks about services and does not talk at all about modules or variables. It's different in the latter context: those names should often be descriptive.

What's the difference, and how do you decide on a cute or descriptive name? A lot of it comes down to how easy the name is to change.

Note: I'm not talking here about names that are part of branding, such as names for companies, products, and published libraries. These have a whole different set of constraints. This post focuses on names in and around code, and ignores this aspect which is critical, but outside the scope here.

If a name is hard to change, and the underlying scope, concepts, and code are likely to change, you should pick a creative name. A descriptive name is a liability for something which changes faster than its name can.

In contrast, if a name is easy to change, it should have a descriptive and unambiguous names. These can get verbose at times, and that's fine. A verbose name is an extra signal that something needs to be split or refactored, since it's now doing more than one thing.

One signal as to whch of these buckets you fall into is whether the name is internal or external to the code under discussion.

What's internal and what's external?

The name of a service is inherently external, because it will wind up referring documentation, configuration files, and other services and clients will make calls to it. If you have to change the name of this service, you have a high blast radius. Many pieces of code (and many people) have to be updated for the change. This makes it very challenging to actually change it, because the cost is so high. It probably won't be changed, causing the underlying functionality and the name to drift apart.

The name of a variable is typically internal, because it's not referenced by other modules, programs, and documentation. Its scope is well-constrained and the cost of updating it is usually very low. Sometimes, refactoring tools can even do the renaming for you automatically, making it nearly free. In these cases your names should be descriptive: never dataset but housevalue_by_address. This aids in understanding the code.

The grey areas

Then there are the ambiguous grey areas. A great example of this is a shared module. It has some elements of both: a lot of aspects are easy to change, but the semi-public API will be harder to change since each consuming codebase has to reflect that change.

In this case, it's really common to see extremely general names. goutils is a shared library that I have named before, which contains—you guessed it—an assortment of useful shared functionality for a few Go services. The library would not be better called alex or sam or another cute name, but it also can't really be fully descriptive or you run into the law firm naming problem. It's auth-logging-config-and-co and then when you get more functionality it expands.

I think this is okay, and it's reasonable for some codebases to be named ambiguous things as long as you don't think you'll get a naming conflict. If there is a naming conflict (two shared Go libraries cannot both reasonably be named goutils) then you have to either go descriptive or cute to get uniqueness.

The marketing problem

One place where you will deviate from this rule of thumb significantly is when naming something that customers or the general public sees. This might be the name of a product, a company, or a library you publish on PyPI. These cases end up much more complicated.

First off, they firmly fall into the "external" and hard-to-change bucket. But in spite of that, different constraints point toward doing something that's sort of descriptive and also sort of cute.

What's the purpose of a public-facing name? It provides a couple of things:

• a unique way to reference the named entity
• some clue on first contact of what the entity is

If you name a published library something like ferdinand, it's not clear what it is. If you name it something like cryptoy, you can at least guess that it's related to cryptography. And libraries like axum-prometheus are clear (for your audience): something that lets an Axum web service export metrics to Prometheus.

So, if the name is what the general public sees on first contact, you have to take a different approach.