How to Better Name Your Functions and Variables

We all know the struggle when naming something in our code. Sometimes we come up with a perfect name in a matter of second — but sometimes we could spend hours and still didn’t come up with a name. Usually, when this happens, you would simply name you variable something like tmp or something even more generic like value . When the problem on how to name something in your program comes up the next time, keep these simple tips in mind. You will not just write abetter and more readable code, but also make the code easier to understand for the person trying to understand it or even for your future self.

When you are naming a function, variable or a class, the same principles apply. You should think of a name as a tiny comment you put in your code. The key idea when naming something is to convey as much information as possible.

Pack information into names.

I know sometimes it is hard to come up with names — a lot of names we see in programs a vague. Sometimes even words like get or set don't provide much information. What exactly are we getting? Is it a variable, an API call or something entirely else.

TLDR;

When naming a function, variable or class, you should keep the following things in mind:

• Choose a word with meaning (provide some context)
• Avoid generic names (like tmp)
• Attach additional information to a name (use suffix or prefix)
• Don’t make your names too long or too short
• Use consistent formatting

Choose a word with meaning

When naming something in your program, always choose a very specific word and avoid using “empty” names. You should be very specific what information variable holds or what a particular function does.

For example, imagine having an API that returns a list of books. In your program, you would probably do something like the following:

function get(url) {
...
}

The word get doesn’t say much about the function. What are we getting? Where are we getting it from — web, a cache may be a database?

Let’s tackle the first question: what exactly are we getting? Since we know we will be getting a list of books, we should incorporate that information in the name of the function. Now we have the following:

function getBooks(url) {
...
}

That’s much better. Now we know exactly what the function does. But one question remains. Where are we getting the data from? We know we will be calling an endpoint and we know we will be getting — fetching the data from that endpoint. Maybe we should also add that information in the name. Here we have two options:

function fetchBooks(url) {
...
}
// OR
function getBooksFromAPI(url) {
...
}

The first options in much cleaner, but sometimes option two would be more descriptive, especially in the case when you have multiple microservices and you want to be very specific which one you are getting the data from.

It’s better to be clear and precise than to be cute.

The main point when choosing a word is to think of what exactly the function does or what value the variable holds. If your colleague reads the code you’ve written, they should know as much about variables and function as you did when writing the code. But be careful — do not overthink it.

Avoid generic names

Names like tmp x a obj and foo are usually synonyms for "I don't know how to name this". Instead of using a generic name without meaning, pick a name that best describes the value or the purpose.

Let’s start with when using a generic name like tmp is ok:

if (right > left) {
  const tmp = right
  right = left
  left = tmp
}

In a case like this, the name tmp is completely fine. The sole purpose of the variable is temporary storage with a short lifetime. The name conveys a specific meaning to the reader — that this variable is here just to hold some other value for a short amount of time.

Not let’s look at an example where tmp may not be the best choice:

let tmp = user.firstName()
tmp += " " user.lastName()
return tmp

Even though the variable tmp is used to hold temporary data; it might not be a proper name in this case. As we learn in the previous section, we should always use a word with the most meaning. Here we should, for instance, rename the variable to something like fullName or maybe to acknowledge that this variable is only temporary we could name it tmpFullName .

The name tmp should be used only in cases when being short-lived and temporary is the most important fact about that variable

Another common usage of generic words — or in this case, letters are loops. Names like i j k are commonly used as indices and loop iterators. Even though these names are generic, they are understood and have a meaning.

Sometimes there is a better name to name your iterator. For instance, imagine the next scenario:

for (let i = 0; i < classes.length; i++) {
  for (let j = 0; j < students.length; j++) {
    ...
  }
}

In this case, you might want to name iterators something like c for class and s for students. This is useful when manipulating the data in the code to avoid bugs and improve readability.

If you’re going to use a generic name like tmp, it, or retval, have a good reason for doing so

A lot of times generic names are used out of pure laziness. Coming up with a great name for a variable is hard, but at least you should give it a try. When you get into the habit of taking a few extra seconds to come up with a better name, it will be much easier.

Attach additional information

As mentioned before, a variable’s name is a tiny comment. Even though there isn’t much room, any extra information you squeeze into a name can make a huge impact on code readability.

If there is something important about a variable that the reader must know, it’s useful to attach that extra piece of information into the name. Let’s, for example, look at the following code:

const start = new Date.getTime()
....
// Many lines bellow
...
cost timeTaken = new Date() - start

There is nothing obviously wrong with the code. Furthermore, this code will actually work in javascript. Variable timeTakes would hold the value of milliseconds. But sometimes to avoid any kind of confusion you could add units to the variable holding the value. For example, you could rename start into startMs . This is a straightforward example, but hopefully, you get the point.

This technique isn’t limited to values with units. You should do it any time there is something dangerous or surprising about the value. For example, when working with sensitive data like password or other sensitive information before it gets hashed. So instead of just using password as a variable name, consider using plainPassword and hashedPassword.

You shouldn’t use this naming convention for every variable in your program. They are important in places where a bug can sneak in, and someone uses the variable in a way it wasn’t intended and can potentially cause a serious security bug.

How to make name just the right size

When picking the perfect name, there is an instant constraint that the name can not be too long. Noone likes long names, and they are hard to read.

newNavigationControllerWrappingViewControllerForDataSourceOfClass()

The longer the name is, the harder it is to remember and consumes more space on the screen. It might take away your attention from something more important.

On the other hand, everyone at some point starts naming their variables, something like d for days or t for temperature, etc.

Shorter names are okay for shorter scope

function checkPasword(password) {
  const s = password.size
  if (s < 8)
    ...
}

Even though s doesn't pack any information it clear to the reader what the variable s is. However, suppose instead of one simple if statement there is a complex checking in that function, the variable would quickly lose its meaning.

Problems with abbreviations

Programmers sometimes resort to acronyms and abbreviations to keep the names shorter. For example, naming a class BEManager instead of BackendManager does save some keystrokes, but could potentially create confusion.

When a new developer joins the team and comes across such name is it clear what the name means? Usually, the answer is yes but sometimes the name might not be as clear as you thought.

Consistent formatting

The way you use underscore, dash, and capitalization also impact the information in a name.

Usually, when a name starts with a capital letter, it marks that the name might be a class. On the other hand, if the name is in uppercase that signifies that the variable is a constant. When a name starts or ends with an underscore, it usually means that this variable is private.

The main goal regarding formatting is to be consistent. Chose a way of naming and stick to it. Nothing removes more from readability that names with different formats.

Summary

If you take only one thing away from this blog post, it should be the following:

Pack information into your names

By this, I mean that the reader can extract as much information as possible from the name.

If you have any comment or additional tips, please leave them in the comment section!