Naming Things Doesn’t Have To Be Hard

Anyone who has spent any time programming knows the truth in how difficult it is to name things. There’s a classic quote from Phil Karlton that most software engineers have probably heard before, namely: “There are only two hard things in Computer Science: cache invalidation and naming things.” At Eagle Eye, we have a standing joke that we need to double the effort required for a ticket whenever we need to name something. I’ve attended meetings just to discuss what something should be called, and I’ve seen the confusion that can arise when something has been named badly.

Yet, even though we take it as a given that naming things is hard, we really should start with the question, “Why is it hard?” To answer this question, I’m going to illustrate it with an example of something I got wrong.

One of Eagle Eye’s central products is the concept of a digital Wallet. Similar in concept to a physical wallet, it’s something owned by a consumer, and it provides access to your money, coupons, loyalty points you may collect over time, and so on.

Early on when I was helping build the APIs for this product, I was tasked with creating a relationship between two Wallets. Each Wallet could have a parent or a child, or both, which introduced hierarchy.

The concept is quite simple to understand, and when I designed how the resource should look like in JSON format, I came up with the following to represent relationships:

{
    “relationships”: {
        “parent”: [1]
    }
}

Now, I can almost guarantee that you’ve assumed that “parent” means resource 1 is the parent. Except, you’d be wrong, because when I designed it, I read it in the context of “this resource is the parent of resource 1” i.e. the word “parent” described the current Wallet’s relationship to the other Wallet.

I hold my hand up and say, “It was a stupid thing to do.”

The interesting thing is that, when I explained the concept and intention to other engineers, they said it was a bit odd, but generally accepted it. However, when we got to implementing it for clients, or engineers in other teams came to it cold, they got very confused because it flew in the face of what they assumed.

This illustrates some of the key points around naming things. When we name something, we name it based on the knowledge we have in our heads regarding context and intent. We know the business rules behind the word, we know what we mean when we build it. Yet, someone else only has a word to go on, and finding words that convey everything we mean and intend is exceptionally difficult.

Which leads us full circle: this is why naming things is hard. It’s hard to give a name to something that carries all the information you intend, because a name without explanation requires us to fill in the meaning based on our own experiences and understanding, and this is where things fall down.

Having said all that, there are principles we can follow that makes naming things a little bit easier.

Conventions Matter

Always realise you only have a word to convey information, and nothing else, which relies on a commonly accepted definition for that word. This means you should pay attention to conventions, and what everyone expects a word to mean.

To illustrate, imagine if you designed a webpage, and you used the word “index” instead of “home” as a link. As engineers, we know an “index” page can refer to the homepage, but to most people, it has very different connotations, like the index of a book. It would be a serious deviation from the commonly accepted convention that the first page of a website is often referred to as “home”.

In addition, words can have many different meanings. The same word can be used as a verb or noun. It can have multiple definitions. Try and identify what most people will understand by that single word. The dictionary and thesaurus are your friends, so use them.

Be Consistent

Consistency is your friend. For example, other entities on our platform had parents and children, so the concept had already been established as to what those words meant, and I should have stuck to it.

If a word already has meaning in your software, giving that word a different meaning in a different context can lead to confusion. If you find yourself doing this, treat it as a bad smell that you may need a different name, or you need to change your implementation to match what’s already there. In my example, it should have led me to conclude that I should name it “parentOf” to be clearer, or I should have stuck to the accepted convention.

Consistency doesn’t just mean keeping the same meaning, it also means reusing the same name whenever you’re referring to the same thing. If you settle on a name for something, don’t suddenly think you can replace it with another name in your code that means the same thing. It would be like calling my entity a Wallet, but sometimes I refer to it as a Purse, or instead of using the term “child” I suddenly used the word “sibling”. This would be incredibly confusing, but far too often, code is littered with variables, classes, and methods that are sometimes named differently.

The Playground Test

A useful technique you can use when naming things is the digital equivalent of the “playground test”. When myself and my wife were coming up with a name for our son, we imagined ourselves standing on a busy playground and shouting out his name. This helped us realise certain names just didn’t work, and sounded daft.

Likewise, you should do the same thing when naming things in programming. Imagine yourself actually using your own software, or picture yourself trying to present it to a room full of people, and describing how it works. Better yet, don’t explain anything to another engineer, just show them some mock representations of what you want to do, and ask them to use it, or describe it back to you.

Reach A Consensus

Probably the best thing you can do is assume that the first name you’ve chosen is wrong. Don’t just accept it. Have a look in the thesaurus at possible alternatives, and discuss your ideas with other people in your organisation that can bring different perspectives.

At Eagle Eye, we’ll often have a quick meeting where we list out our options, and go through them one by one. Sometimes this is even done long before it reaches engineers, but we’ll still discuss it and come to a consensus. Having a few people that are not all software engineers in a room helps give some idea of how a word is commonly interpreted, or how a non-technical person interprets a word.

Have A Common Toolbox Of Words And Definitions

One thing we do at Eagle Eye is try and provide guidance on how to name things, such as when to use plural or singular, how to construct namespaces and class names, and how to name GitHub Projects. In the latter case, we have defined the structure of the name, and identified various terms (such as sdk, skeleton, models etc.) and defined their meanings.

The point here is that, while you can’t necessarily define all the possible names, what you can do is try and impose certain rules to the structure of naming things. I liken it, in a way, to poetry. Sometimes, you can impose certain rules around rhyme, meter, number of syllables, and so on. Rather than being prohibitive, it can free your mind to focus on what you want to say.

Over time, your software will develop certain conventions, and it’s critical to document and define these so everyone is aware of the existing glossary. This helps you avoid the situation of using the same name somewhere else.

Stand On The Shoulders Of Giants

As software engineers, we are working in a time where there is so much code out there in dozens of different programming languages that it’s unlikely we are facing problems that others have not. Researching for something similar that someone else has done is useful to make sure you’re not reinventing the wheel.

If you are going to build something, take some inspiration from the names and conventions others have used before you. Stack Exchange, blogs, open source code on GitHub - the internet is your friend, and should inspire you.

Pay Attention To Names In Code Reviews

Names are an often overlooked aspect of code reviews. If you’re reviewing a piece of code, you should pay attention to the names of classes, methods, variables and so on, because they are what you rely on to understand what the program is doing. Sometimes, you may know the correct term that should be used because it was used elsewhere in a part of the codebase that the current engineer is unaware of. If you’re reviewing a piece of work, and you make an assumption as to what a method does, or what a class is, based on its name, but you realise that that assumption is wrong, treat it as a code smell, and mention it.

Name Things For Humans, Not Machines

Donald Knuth famously remarked that, “Programs are meant to be read by humans and only incidentally for computers to execute.” As such, choose names and formats that make sense for the programmer. Aim for clarity, not just brevity. Using $x for a variable name is not as informative as using $totalFoo, for example.

It’s Not Just About The Name

Explaining your intentions in a single word is hard. Sometimes no word seems perfect, and you just have to make a decision. However, the truth is we don’t have to always depend on a word. We can write documentation, and share it with other engineers or clients. We can write comments in our code to help explain things to the next engineer that comes along.

While having a good name for something is important, you can’t get away from the fact that, in software, you’re taking words used in our everyday language, and reapplying and reinventing them for the digital world, with business rules and a host of other new meanings that are not obvious. Good, clear, concise and up-to-date documentation is still necessary, and doubly so if a name can be confusing.

You’re Human

The last point here is a simple one: you’re human. You’ll still get it wrong from time to time, so cut yourself some slack. Language is messy and complicated. I always have a laugh whenever the “relationships” question gets asked, and think, “Here we go again.” Crucially, however, we all learned from it, and it’s helped us get better. Naming things is still hard, but at least we’re not making it harder for ourselves.