Codenames

Have you ever found yourself staring at a codebase, scratching your head as you try to decipher cryptic names like dyn_rtr_srv or id_svc? Or maybe you thought naming your error handling module the-upside-down was a clever nod to Stranger Things, but now your logs are filled with mysterious messages about demogorgons and eleven?

Naming things in code is notorious, but it doesn’t have to be a nightmare. By following a few guiding principles and embracing a bit of creativity, our worst vices can be avoided.

Building Blocks

The narrowest units of code - functions, variables and classes - are often the most simple, they should be descriptive and ‘self-documenting’. Come back to names after finishing your first draft, and then attempt to pick a name that is as descriptive as possible.

1. Describe the code’s purpose.
2. Use longer names; laziness limits length naturally.
   • Excessively long names suggest you need a rewrite
   • and/or are banned, if you want to use them, create 2 new functions.
3. Rename often, if you didn’t understand it, change it (especially if it is not your code).

Codenames

When it comes to naming services, projects, servers, endpoints, and APIs in your codebase, a different approach is required compared to our building blocks of code. The key difference lies in the nature of these entities. Variables and functions are typically descriptive units, their names reflecting their specific, well-defined responsibilities. In contrast, the larger scoped items we’re discussing here are more akin to “codenames”—identifiers that are resistant to change and represent a potentially unbounded set of functionalities.

Once a codename takes hold, it has a funny way of sticking around. It gets thrown around the office, typed into emails, and even added to documentation. Before you know it, that codename has become part of your project’s very identity. Trying to change it later can feel like convincing your colleagues to call you by a new nickname.

But here’s the thing: codenames often outlive their original scope. That compact little service you christened “Hermes” might one day grow into a sprawling system that handles everything from user authentication to data synchronization. As your project evolves, its codename remains constant, even if its meaning morphs over time.

So how do you choose a codename that can stand the test of time and growth? It’s a bit like picking a tattoo design - you want something that will still look good and make sense years down the line, even as your interests and style change. It’s a challenge, but with a bit of foresight and creativity, it’s definitely doable.

These are my guidelines when choosing a codename:

1. Be “suggestive” without being “descriptive”.
   • Prefer gatekeeper over identity-service
2. Use cuter ¹ codenames for more abstract or fungible concepts.
   • 3-rapid-mice over V1StG for run identifiers.
   • bonbon over hertzner-eu-west-2 for server names.
3. Avoid fun² references.
   • octopus is better than dr-octopus.
   • bouncer is better than heimdall.
4. Separate marketing names³ from codenames.

Be Suggestive, Not Descriptive

Long descriptive names like dynamic-routing-service, in my experience, will morph into drs, and leave you in a worse state than the most cutesy name. Generic yet descriptive names, such as search-engine, risk being reused and becoming ambiguous. A once descriptive name like identity-service may mislead as scope creep occurs.

Use Cuter Names for More Abstract Concepts

My experience with cutesy names started with server names (“boxes”). You’d often:

• Rebalance which services went on which box - they were mostly interchangeable.
• Apply a theme to help you remember groupings; all internal servers were Greek Gods ⁴ - Zeus was in the cloud and Athena had the most memory.

A cute name is good for recall, but also can subtly imply intent.

However, keep in mind that you don’t want to go crazy with cute names. New hires will suffer; you don’t want to get into the dark path of hundreds of quirkily names things to navigate.

MakerDAO is my cautionary tale - it has a glossary for its 167 unique codenames. For example:

• cat (liquidations) can bite (initiate liquidation) or flip (liquidate collateral)
• vows have sin, sump, dump, bump and hump properties.
• Auctions can be flippers, floppers or flappers.

Avoid References

Think to yourself, do you need to know anything for the reference to be meaningful? All of these are projects I’ve been on, and had to explain the name for:

Greek/Roman Gods - are you relying on people to know that Zeus is the god of the sky, and Athena is the goddess of wisdom.

Star Trek Characters - are you relying on knowing Kirk is the captain, and Spock is logical?

Greek Philosophers - are you relying on knowing Socrates was Plato’s teacher?

Star / Galaxy names - are you relying on knowing Proxima Centauri is a star in Alpha Centauri?

If not, you could use these names, and lose the benefit of being “suggestive” to everyone.

Remember, your theme will eventually breakdown and become increasingly obscure. For example, Grafana has/had a cute naming scheme.

Tom Wilkie: We’ve got this LGTM strategy, like logs, graphs, traces, and metrics. Loki, the logging system begins with L, Grafana the graphing system with G, Tempo, the tracing system with T … and [had] Cortex, the metrics system with a C. So it had to begin with an M. And then we went back to our Scandinavian roots. We were looking for a word that began with M that came from mythology and that’s where we came up with Mimir.

But, there’s also Prometheus the monitoring system that begins with a P.

Ignore Public, Marketing Names

Marketing names are not codenames, they should be simple, follow the customer’s desires, be tested, and easy to iterate early on.

How can I tell if a name is “suggestive” or “descriptive”?

US trademarks are great for dialing in your intution for suggestive names. When you’re trying to trademark a name, you are allowed to find something that infers from the dictionary definition, but is not directly related.

For example:

• Coppertone (sunscreen)
• Greyhound (bus)
• Energizer (batteries)
• Raindance (car wax)
• Tesla (electric car)
• North Face (hiking gear)
• Travelodge (hotel)