Codenames

Ever stared at a codebase, scratching your head over dyn_rtr_srv or id_svc? Or named your error handling module the-upside-down as a nod to Stranger Things, only to fill your logs with messages about demogorgons and eleven?

Naming things in code is notorious, but it needn’t be difficult. 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

Naming services, projects, servers, endpoints, and APIs requires a different approach. Variables and functions are descriptive units with well-defined responsibilities. Services and APIs are “codenames” — identifiers resistant to change that represent an unbounded set of functionalities.

Once a codename takes hold, it sticks. It gets thrown around the office, typed into emails, added to documentation. Soon it becomes part of the project’s identity. Changing it later feels like convincing colleagues to call you by a new nickname.

Codenames often outlive their original scope. That compact service you christened “Hermes” might grow into a sprawling system handling everything from user authentication to data synchronization. The codename stays constant even as its meaning morphs.

How do you choose a codename that stands the test of time? Like picking a tattoo — you want something that still makes sense years later, even as your interests change.

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.

Don’t go overboard. New hires will suffer navigating hundreds of quirkily named things.

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.

Your theme will eventually break down and become obscure. 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 sharpen your intuition for suggestive names. When trademarking, you can use something that infers from the dictionary definition but isn’t directly related.

For example:

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