Name Configuration Management Analysis Blog

A good name is more desirable than great riches; to be esteemed is better than silver or gold. Proverbs 22:1

I recently helped pick out some system names on a new project. I was lucky enough to be in the driver’s seat when it came time to name the new applications. My pair and I kicked it around for a little bit, then we came up with the suiting metaphor of a dinner party. We had a hostess that was the up-front experience for the user, a kitchen where the bulk of the business logic resided, a waiter who was the interface to the kitchen, and a pantry where the data was stored.

I have always valued rich names in my code. The Extreme Programming practice of System Metaphor has always served me well. I suppose I’m even a little bit notorious at 8th Light for picking extreme metaphors. Colin often reminds me of the time when we were implementing a timer ‘gun.’ ‘Bullets’ were ‘loaded’ into the gun and they ‘fired’ at a later time. I’m pretty sure there was a method named ‘lock_and_load.’ Limelight is another great example. We had a blast picking those names. You don’t just build a limelight app, you put on a ‘production’. You make ‘stages’ and place ‘actors’ and ‘props’ on them.

So what’s with all the funny names? Are they adding any value or are they just something to amuse me?

Let’s take a peak at the alternative. I often challenge bad names with a tongue-in-cheek expression that goes something like this: “Just take 3 or so meaningless names and put them together, and now you have a meaningful name.”

Have you seen some names like this in your system?

  • Management Service Control Panel
  • Gateway Console Api
  • Server Client Interface
  • Site Protocol Manager
  • Thing Thingy Other Thing

Ok, so maybe you haven’t seen that last one, but I’m sure you have come across many systems with long meandering names like this. I once worked on a system that had a Management Console, a Management Service, and a Management Service Console. No joke.

Well my ‘dinner party’ pair and I faced some resistance to our ‘weird’ names. Listening to our teammate’s objections has made me really think about this practice of metaphor and why it is so powerful.

Unused real estate in your brain

Once you have several similar-sounding 3-word names, keeping them straight in your head becomes difficult. What if you are the new person on a project? You are lost in a deluge of similar sounding words and letters that have nothing to do but sit in a big jumble in your brain.

Something interesting happens when you use a metaphor that is a bit ‘out there.’ The metaphor finds a nice clear place in your brain to reside. There is nothing like it, and nothing to get confused about. It’s like moving the system out to the suburbs where land is cheaper and competition is low. (That last sentence was a simile and not a metaphor, by the way.)

Names chosen from a good metaphor may have little to do with the actual business language of the application. Learning the system may take some time. A newcomer must discover what each component does. But this is certainly no more difficult than the same task would be with longer, more generic names.

Communication

Rich names are so much easier to communicate about. Compare these two conversations.

“Hey Jim, I need to make a change in the kitchen, are you guys in there right now?”

“Nope, we are working with the waiter, go ahead”

vs

“Hey Jim, I need to work on the Management Service, are you working with it right now?”

“Yeah, we’ve got a big commit about to go in for the Console.”

“Wait, you are in the Management Service Console or the Management Service client api?”

“Oh, we are working on the client side of the management console api.”

“I just need to make a change to the Management Service Server. Are you working on that?”

“Wait, which one is that?”

“The Server Service that hosts the api that the client service api talks to.”

“Huh?”

You are already doing it

If you stop and think about it, nearly every name in a software system is a metaphor. A client is someone who hires a lawyer to represent them in court. A manager is a person who oversees a department in a company. A gateway is a hole in a fence that opens and closes to let people in and out.

What I’m suggesting isn’t a wild departure from what you already do. I’m just suggesting that you drop the tired, overused metaphors in favor of some unique ones.

Ubiquitous use

Eventually, through use, every name that you choose in your system will take on meaning. You could argue that words like api, service and client are ubiquitous words that already have significant meaning because they are used throughout your company. I agree that it is valuable to build upon names that a group of people already use frequently. But how did those particular words come to be used? Someone picked a name at some point and it stuck. It took on layers of meaning as the company developed a shared understanding of what the name meant.

The meaning of system names comes from frequent use, not the other way around. Any name you choose will eventually be used and understood by everyone who interacts with the system. What matters is how often the name gets confused with something else and how long it takes a new-comer to learn and understand your names. Rich names from a strong metaphor help team understanding propagate quickly.

Professionalism

The names that I call rich, you could also call juvenile or unprofessional. Software, after all, is a serious business. I believe that one of the practices of a professional software developer should be the ability to pick good names. If you are able to do this you will help those around you and ultimately save your team and employer time and money. That sounds to me like the approach that a professional would take.

Doug Bradbury, Software Craftsman

Doug Bradbury is a maker, a thinker, a craftsman, and a learner.