Naming is easy! A guide for developers

There is an old joke in programming circles: 

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

The first is truly hard, the third is the joke, but the second one? That one baffles me. Naming things is easy, or at least it should be. But for reasons unknown, we make it hard. Just call it what it is or what it does. But for some reason, we developers have an aversion to doing that. Here are some thoughts about why naming is hard for developers, along with some ideas for doing it right.

Nine reasons for bad naming

1. We assume everyone knows what we know
2. Meaning drift
3. Sheer laziness
4. Too eager to abbreviate
5. Forgetting functions are verbs
6. Inconsistency
7. Going negative
8. Prefixing
9. Blah words

We assume everyone knows what we know

This is the most common reason that we name things badly. I know that EmpNo stands for EmployeeNumber, and that EmployeeNumber is the unique ID in the database. Why wouldn’t everyone else? Well, because the next poor developer who comes along might think that the EmployeeNumber is the number assigned to the employee for logging in, and has nothing to do with unique values in the database. 

If EmployeeNumber is the unique ID in the database, why not just call it that? How about calling it EmployeeUniqueIDInDatabase? Sure, it’s a bit of a mouthful, but no one will ever mistake it for something else, right? 

And if you say to me, “Nick, that’s too much typing!” I’ll give you my standard response: Lazy is no way to go through life, my friend. Plus, these days, your IDE will do all of that typing for you. A long, clear, explanatory name is always superior to an abbreviation you think is obvious but really isn’t. 

Meaning drift

Sometimes the meaning of a name can be less precise than it might be, and that meaning can drift over time. You might start out with a method called SaveReceipt that puts a copy of the receipt in the database. But over time, you may add printing to the routine, and move the actual saving to a different method, and suddenly your name is lying to you. Naming it SaveReceiptToTheDatabase in the first place might make that harder to happen.

Sheer laziness

While naming things isn’t hard, it does take a bit of thought. I guess some folks just don’t want to take the time to think about naming things. I’m not even going to talk about how silly it is to use a single letter for a variable name. The only exception I’ll quarter is using i as the variable in a loop. (But I’ll argue vehemently that Index is better.)

Otherwise, give a variable a really good, full name. Sure, it may take some effort, but if you stop and ask, “What, exactly, is this thing?” and then name it based on what your answer is, you’ll have a great name. For instance, if you feel the need to do this:

If (EmployeeNumber > 0) and (OrderNumber >  0) {
 // ...
}

Don’t be afraid to go the extra mile:

EmployeeIsValid = EmployeeUniqueIDInDatabase > 0;
ThereIsAnOrder = OrderNumber > 0;
ItIsOkayToProcessTheOrder := EmployeeIsValid and ThereIsAnOrder;
If ItIsOkayToProcessTheOrder {
  // ...
}

That is massively more readable, and the variable names clearly explain what they represent. It would be very hard to confuse what is happening there, and it reduces the cognitive load of the next developer, who no longer has to parse complex boolean statements. 

Too eager to abbreviate

Laziness isn’t good, but neither is being in a hurry. Being in a hurry might cause us to abbreviate things when there is no need to do so. Remember, the IDE will do a lot of typing for you. You might think you’re saving .876 seconds by typing acctBlnc instead of accountBalance, but really you’re just stealing precious hours from the poor guy maintaining your code. 

And while we are at it, whose account balance is that? The company’s? The customer’s? Who knows?

Why developers are afraid of long names is a mystery to me. Don’t abbreviate anything unless it is an industry standard like URL or HTTP. Again, just type it out.

Forgetting functions are verbs

All methods should be named as verbs and should completely describe what they do. getCustomer is good, but where are you getting the customer from? What, exactly, are you getting? getCustomerInstanceFromDatabase is better. Again, if you ask yourself, “What is this function doing?” and then just name it based on your complete answer, you’ll have more maintainable code.

Inconsistency

It’s easy to be inconsistent. For instance, if you use the word Customer to mean a person standing in front of the point-of-sale system buying something, then make sure that is what you call them everywhere in the system. Don’t use the word Client to describe them, ever. Don’t call them Buyer in some other module. Use the same term for the same thing consistently, throughout your repository.

Going negative

As I mentioned a couple weeks ago, keep names positive, particularly Booleans (if you must use them). Names like isNotValid and denyAccess become abominations. For example:

if (!IsNotValid) or (!denyAccess) {
  // ...
} 

There is a reason we don’t use double negatives in the English language. You also should avoid them in your code.

Prefixing

Back in the day, Hungarian notation was all the rage. All names had a prefix that defined what they were in addition to the name. This has gone out of vogue, as it got complex. I prefer that the name be expressive enough to allow the maintainer to surmise what it is. For instance, EmployeeCount is obviously an integer, and FirstName is obviously a string.

Some people like to prefix their variable names with a letter to indicate the role that a variable plays in a method—for example, ‘l’ for local variables, ‘a’ for method arguments or parameters. and so on. I frown on this kind of thing. If your methods are so big that you can’t tell at a glance what role a variable is playing, then you need to refactor. 

Blah words

Another thing to avoid is using words that have no real meaning but seem important somehow. Avoid words like Helper, Handler, Service, Util, Process, Info, Data, Task, Stuff, or Object. These are “blah words,” or naming junk food—empty words that serve no purpose. What method do you write that isn’t helpful? Which ones don’t handle something? What in your app isn’t actually data? How much code do you write that doesn’t perform a task?

Naming is easy

Naming things is easy, or it should be. Like many things in life, it can all go well if you avoid doing bad things more than worrying about doing good things. Good naming dramatically reduces the cognitive load when maintaining code. By making the code clearer, it helps developers avoid mistakes and introducing bugs. The mere seconds it takes to stop and think about a name can save literally hours down the road.

Coding for clarity and maintainability is always the way to go. Naming things properly, completely, and clearly is a huge part of writing good code. Besides, to paraphrase the famous saying, “Name things like the person maintaining your code is a sleep-deprived psychopath with your home address.”