Codenames

Ever stared at a codebase, scratching your head over dyn_rtr_srv? Or named your error handling module the-upside-down, only to fill your logs with demogorgons and eleven?

Building Blocks

The narrowest units of code - functions, variables and classes - should be descriptive and ‘self-documenting’.

1. Describe the code’s purpose.
2. Use longer names; laziness limits length naturally.
3. Rename often, if you didn’t understand it, change it.

Codenames

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. That compact service you christened “Hermes” might grow into a sprawling system. The codename stays constant even as its meaning morphs.

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 will morph into drs. 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”) - mostly interchangeable, with a theme; 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.

MakerDAO is my cautionary tale - it has a glossary for its 167 unique codenames. cat (liquidations) can bite (initiate liquidation) or flip (liquidate collateral).

Avoid references

Do you need to know anything for the reference to be meaningful?

Greek/Roman Gods - are you relying on knowing 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?

Your theme will eventually break down. Grafana has/had a cute naming scheme.

Tom Wilkie: We’ve got this LGTM strategy, like logs, graphs, traces, and metrics. … So it had to begin with an M, 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.

• Coppertone (sunscreen)
• Greyhound (bus)
• Tesla (electric car)
• Terraform (infrastructure as code)

When you need uniqueness, compound

A company name or a .com where every plain English word was registered decades ago needs help: fuse two suggestive words.

• Raindance (rain + dance for ‘car wax’)
• Greptile (grep + reptile for ‘searching + eating bugs’)
• Datadog (data + dog for a ‘data watchdog’)
• Roomba (room + rumba for ‘floor dancing robot’)

Duds:

• Diffodil (diff + daffodil for ‘diff reviewer’) - bad because daffodil does no work.
• Craterpillar (crate + caterpillar for ‘Rust packaging’) - bad because the eye reads it as crater + pillar.
• SQLirrel (SQL + squirrel for ‘database backups’) - bad because it is tricky to pronounce and has a non-intuitive spelling.
• Backpropeller (backprop + propeller for ‘AI lab’) - bad because the mental image is weird (a propeller going backwards?).