Clear Names

Naming things is one of the two hard things in programming—cache invalidation is the other one. I wish there's an article or a book that makes me master naming my variables and functions. There isn’t any because no one knows what your code is supposed to mean except you.

That said, there are some things that if you avoid when naming, you will have better named things—this is what this article is about.

#Avoid abbreviations

Some people think that the shorter the name is, the clearer it would be. But actually the opposite is true. Naming a variable user is much clearer than just u.

When a new developer is looking at your code (or even you after a while) and seeing u, they most likely wouldn't know what that means until they go back and see where that value is coming from. Most of the time that's not needed—sometimes, I just need to understand some function in the code without having to read other stuff to know the value of some variable.

#Be more specific

Sometimes I have the opportunity to be more specific about the value the variable contains. Being more specific makes the code clearer and easier to reason about.

Taking the same example above, it's better to name the variable loggedInUser instead of user if that variable contains the currently logged in user.

#Avoid generic terms

There are some names that can be used for anything—like item. While they are not wrong in terms of the meaning, they can make the code less clear.

These kind of names are usually seen in loops. For example, if you are looping over a list of tasks, instead of naming each individual element as item, name it task.

Using generic terms can makes things even worse when you are using it multiple times in the same code block.

An example would be looping over two lists in the same function. If you name the single element of a task list as item, and you name the single element of a project list as item, then you might confuse one with the other while reading the code of that function.

#Explain clearly what it's doing

There's nothing stopping me from explaining what a function is doing through its name. If you have a function that hides archived projects, then call that function hideArchivedProjects instead of just hide or hideProjects.

Another example: if you have a function that checks if a user can get a discount, call it canAUserGetADiscount—be as specific as needed.

This will not only make your function have a clear name that shows its intent, but it will also make comments redundant—if you've ever heard that comments are considered a bad smell it's because you can make your code clearer in a way that explains itself without the help of comments.

#Hidden indications

Bad names sometimes indicate that part of your code is poorly designed and can be improved.

If you see a function name has the word And then it might indicate that your function is doing two things, and it's better to split it into two functions.

Sometimes that's what you want, but other times it's an indication that your code needs improvement.

Let's say you have a function named fetchUserAndUpdate. This name shows that this function is doing two things: fetch a user and update a user. For this example, it's better to split it into two functions: fetchUser and updateUser. The reason for that is because after the split you can fetch the user as many times as you want without updating it. This is what we call separate queries from mutations.

Another hidden indicator is repeating the same word in multiple functions. Sometimes this means there is a relationship between these functions and it's better if they are grouped together.

For example, if you see the word user in a lot of functions, like getUser, updateUser, and deleteUser, then maybe they should live together under the same class—User.