There are only two hard things in computer science: cache invalidation, naming things, and off-by-one errors.

– (sort of) Phil Karlton

Obligatory Martin Fowler link

As developers, one of our most challenging tasks can be naming things. In modeling a domain, precise naming can make or break a new developer’s ability to jump into a codebase. When naming variables on a line-by-line basis, it’s important to use descriptive names like currentProduct and newUserId as opposed to data, shiz, or curVal (yes, I’ve seen all of these). These are each fantastic posts in their own right, but today’s post deals with the high-level naming of projects. I’ll argue that these should be named using codenames and back it up with some examples - both good and bad - that the Rally Choice group has encountered.

Projects should be code-named

As a developer, you’ll have the opportunity to name a large number of projects over your career. The best option is to use codenames which are dissociated from the business/marketing name of the project and independent of the project’s exact functionality.

Product names are free to change at any time, so binding a project name to a product name is a poor decision. In turn, projects’ functionalities change throughout their lifetime: software is awesome in part because of its flexibility to change over time. Since you can’t predict what your code will have to do in two years’ time, don’t bind its name to its functionality. From an engineering perspective, you are tightly coupling your project’s name to some other component which is going to change.

Instead, use the software engineer’s greatest asset: a level of indirection. Use codenames which are arbitrary and independent of anything in the project. This de-couples your project’s name from its purpose or current responsibility set.

But that sounds like you’re just pontificating: prove it to me!

Okay, can do - I’ll hand out a contrived pedagogical example, then add some concrete examples from Rally Choice’s past.

Contrived example

As an up-and-coming developer, you’re thrilled to be invited to a meeting(!) where the product team asks you to start a new project which is going to disrupt the Big Sunglasses industry by allowing people to share shades: Uber for your Oakleys. The marketing team has already decided that its customer-facing name is to be Shadur.

You excitedly pull open your IDE and start up a new project in the latest programming language you found on /r/programming, but are faced with your first problem: what do you name it? A few options:

  • (a) Shadur: the marketing name
  • (b) SunglassesSharer: a description of what the project actually does
  • (c) AquaIronBoxer: you pulled open and went with the first suggestion

As a doe-eyed new developer, you’d probably choose option (a), since that’s precisely what the product team told you to do. With a little more experience, you might abstract the concept into option (b) to reflect the underlying concept better. Let’s see how those go…

Six months later, the marketing team does some user acceptance testing on the product name, and it turns out that it’s terrible. They rebrand to ShadeShare. Hopefully you didn’t choose option (a), because it’s now incorrect!

Three months further down the road, ShadeShare is exhibiting hockey-stick growth and it’s time to scale the business. Bizdev goes out and sells the capability to share reading glasses too. Hopefully you didn’t choose option (b) either, because it is now an incorrect name as well!

Five years later, as you relax on the pile of cash you received from your exit, you reflect on how great of a name AquaIronBoxer was. It allowed your code to live on independent of the business team’s decisions and the product team’s requirements. It freed up so much time for you that you could worry about more interesting things like scaling to the billions of users who are chomping at the bit to share their spectacles. Oh, what a great decision option (c) was!

Cool story bro, but I’m still not sold. Is this really how the world works?

Fine, fine - here are some examples from where this has actually happened in Rally Choice’s history.

Rally Choice History

When the Choice product was first launched, it was branded as a product called Tenzint. The code projects were all named Tenzint.[Thing] and all was well.

Then, eight months later, a new name was chosen: Tenzint was now Spotlite! The rebranding was great, but it introduced dissonance into our codebase: some things were named Tenzint, some newer ones were Spotlite. But that was no big deal - engineers are generally good at #DEFINEing words to map to each other. Within a couple of years we got rid of all of the Tenzint references and replaced them with Spotlite.

That was great, until the company was acquired by Rally Health. Then it was time to rebrand again. Over the next year, the product (and line of business) went through a series of naming candidates, which introduced a good deal of confusion into the naming of the projects and packages of our web sites. If only we’d codenamed those!

There’s a silver lining, though: the business-name mistakes only went as far as the primary web projects. In the intervening years, we had adopted a microservices architecture and chose a codenaming convention for them: birds of prey. Some examples, along with how their responsibilities have varied over time:

  • Vulture: Began life in 2011 as an insurance rates quoting engine. After a couple of years, gained responsibility for insurance eligibility as well. A couple of years later, gained other tasks surrounding enrollment. Recently lost certain tasks surrounding enrollment.
  • Hawk: Began life in 2012 as an eligibility rules engine. Shifted to become an arbitrary-input-and-output configurable decision engine. Shifted to and from being a library and independent service.
  • Caracara: Introduced in 2015, began life as an API framework. Shifted to owning a broad swathe of our data layer. Shifted again to a smaller component of our data layer, owning only core concepts around broadly-shared entities.

Each of these components, if named by the business or by their responsibility, would have either undergone name churn through the years or would now have a name which is wildly inconsistent with its actual responsibilities. Instead, we’ve slightly redefined services over time, and the codename paradigm is flexible enough to accommodate that.

Not only are the bird-of-prey codenames cool, but they add a certain level of camaraderie within the Choice team - there’s always excitement when someone gets to name a new bird, and colorful conversation over what the best bird name would be. There’s a bit of a learning curve for the vocabulary, but it’s well-documented on the company wiki and new developers tend to learn the project names fairly easily.

In summary: bring high-quality engineering to the table even when you’re just naming things. Decouple project names from other concerns by using a codenaming paradigm. Your life will be better.

And if you decide on a fun framework for generating those codenames, you might just give a a little boost to your culture as well.