Code Names Are Bad

Code names, for internal projects, are an easily avoided, unforced error. Naming things that way makes everything harder for new people, partner teams and the rest of the business. It won’t kill your org’s productivity but it will lower it by a few % points, especially if you have a steady stream of new people or new services.

Using code names is similar to not using a code formatter

I was inspired to write down this by Aaron Zinger’s post Software Names should be Whimsical and Cryptic which puts into writing the common arguments I’ve seen for code names. It made me realize a lot of the discussion is people talking past each other as mostly this debate happens in meeting rooms or twitter threads which makes it hard to grapple with the arguments.

What we’re arguing about

When a team spins up a new service there are a lot of decisions to make. One of the seemingly trivial ones is what to call it. Most people don’t have a strong opinion on this topic, because it’s not a major decision comparatively. Also naming is famously hard. But the git repo and the services need a name. So sometimes people will come up with “clever” themed names.

For example if it’s a billing service that calls to Stripe to do the recurring billing you could call it ScroogeMcDuckService and the git repos would be called ScroogeMcDuckInfrastructure and ScroogeMcDuckLibrary. The better alternative would be to call it BillingService, BillingInfrastructure BillingLibrary.

Having a code name for the public facing part of the project is a separate conversation as marketing and googlability becomes important. But for internalling facing systems you should prefer Billing over ScroogeMcDuck.

The main reason people do this is that it’s “fun” and the only people who need to approve the naming decision are the engineers who are implementing the service, and are therefore intimately familiar with it. The name doesn’t really mean anything to them.

The code name makes them laugh and they don’t have to think about it

Arguments against codenames

Making communication harder

Then ScroogeMcDuck needs to depend on the subscription service, called Sisyphus and the teams need to collaborate. You can easily imagine a situation where these two teams are having a cross team review, where half of the meeting is each team having to reference the glossary to remember what each of these services does. Because it won’t just be ScroogeMcDuck needs to call to Sisyphus it will be. “ScroogeMcDuck calls to Sisyphus then RichieRich and Ouroboros for any special statuses, then DarkwingDuck to decide to call Stripe vs Paypal, after it needs to update Midas and Teller”

From context you can infer and make assumptions about what each of these does, but it’s additional cognitive overhead to keep track of instead of thinking about the design. It makes reviewing the actual problem harder for no benefit.

Every team needs a glossary for acronyms and domain jargon. No one needs an entry on “DarkwingDuck is the service that controls A/B testing”

Or a new person joins, or the people who came up with the name leave. For programmers the average is every two years. Now that person needs to learn a bunch of code names. Again it makes communication harder for no reason, especially for the new person.

Code names are a form of gatekeeping on new people

I once had a tech lead when I joined a large established tech company who was kind enough to sit me down and explain to me, over the course of a few hours the history of why things were named the way they were. I apprecieated the effort, but he wouldn’t have needed to do it the dependent teams hadn’t decided to name their services after 80’s bands. These were internal platform teams and to onboard with them, or even to know which team you needed to talk to you first needed to know what all the code names meant and their history. Which meant a new person who didn’t know what all the names meant couldn’t be successful.

Your code names are uncreative

A secondary issue for me is the aesthetic’s, in that they’re rarely very creative. Usually one of the first few teams choose a name, then everyone feels obligated to fit that theme. Which besides hurting communication, means that one of around a dozen possible themes gets chosen. Greek gods, $CURRENT_POPULAR_TV_SHOW or classic scifi are the most popular.

I have never worked at a place without at least two Athenas

Once you’ve worked at a few different places, or even a few differnt orgs in a large enough company you realize that the names usually either aren’t very creative, or if they are creative are just an in joke. The most creative one I ever encountered was a HoneybadgerService, which was chosen by a team I was the tech lead of. They asked what to name a new service while I was on paternity leave and I crankily replied “I don’t give a fuck”

Although creative, that led to the entertaining experience of explaining to McKinsey CEO why we thought HoneybadgerService would drive new customer adoption at a low CAC. More generally I’ve had a career working with the business side including legal. And while they generally understand that we as developers are from a different world, it still makes it harder to communication with them.

Arguments for code names

What if what the service does changes?

The strongest argument I’ve heard, and Aaron brings up “I did a search on Github READMEs just now for the phrase “despite the name”. About 20,000 results.”. The counterpoint is github has over 200 million repos. It’s a question of whether you would prefer to have to explain what each of your 30 microservices with cute names do or explain why a single service does something slightly different than it’s name.

Put another way, without scrolling back up, is it easier to remember what ScroogeMcDuck, Sisyphus, RichieRich, Ouroboro, DarkwingDuck Stripe, Paypal, Midas and Teller do or is it easier to remember that the SubscriptionService also handles refunds for subscribers?

Need a cool name for marketing

Having a cool and whimsical name for an open source library makes sense as the project is customer facing and needs marketing. Any customer facing part of the project is a separate conversation as marketing and googlability becomes important. But for internal facing systems there shouldn’t be a marketing concern.

What if the name is taken

Then that service probably does what you wanted your service to do? By not being cute with your name you and that team deduplicated a lot of effort. If that’s not the case you might have to think of a better name

But it’s secret

I have previously had literal Top Secret security clearance and dumb code names seemed to be some sort of requirement. If you aren’t an actual secret project, but instead a commercial project your secret probably isn’t that important. And if your project is a success then you won’t be secret anymore and all the people you hire to work on Dulcimer are going to have a hard time

Everything in the company has dumb codenames, are you saying we should fix that?

No. Renaming services is hard enough that it’s likely not worth the effort. Make a glossary of all the code names and don’t make the situation worse going forward. As those services are deprecated, replace them with useful service names.

What about team names?

Teams change what they do much more frequently than microservices do. That means the “changes what it does” argument from above holds more weight.

You’re a kill joy

That’s fair. I’ve written a rhyming children’s book about programming and blogged about Daniel Tiger being our post scarcity future. But on this I’m a killjoy. But I’m killing your joy for 2 hours of you laughing at a ‘clever’ name and then not thinking about again vs you making everyone’s life harder.

Other articles about code names