Naming matters

Naming your code correctly can save you and your colleagues a lot of time.
Whether it is a simple variable or a complex function, naming has a crucial part in reading and debugging code, and since we spend more time reading code than writing it, it’s important that we pay attention to this, sometimes neglected, aspect of programming.

The value of correct code naming is so evident in every hour I spend reading code and in this post I would like to share with you some of my practices and code naming rules of thumb.

Variables

We all create variables, but we sometimes don't take the time to really name them correctly. The reasons for giving a poor variable name may vary but mostly it’s because we wanted to do something real quick, just to make sure it works, and we leave that t variable there to puzzle future maintainers (usually ourselves).

Though trivial, my rule of thumb when it comes to variable naming is -

A variable name needs to indicate its meaning as precisely as it can

I don’t really care whether it’s a Number or a String. I do however care if it represents the amount of items or the user name.

You may think that the above is trivial but I bet you can find many places in your code where a variable name was misleading and made you go logically astray.
You will read this variable name over and over for many times so you might as well set it to help you.

Let’s dive a little deeper to the different variable types and how they might affect the name we choose for it -

Booleans

The rule here is quite straightforward -

Boolean variables represent a yes/no question. I will ask “Is this view in fast mode?” or “does this object have items?”

And this will produce straightforward variable names, such as isInFastMode in the view scope or hasItems in the object scope. I consider the alternative of fastMode and items a bad practice and misleading. I rather have my conditionals read as close as can be to plain English, e.g. if(isInFastMode) instead of what I consider a crooked English syntax, e.g. if(fastMode).

Collection vs. Single

Sometimes you have a collection, say items, and inside this collection each object is a single item. If we take these as they are and use them for variable names we will be facing a problem.
The problem is that 2 different variables which can be differentiated only by a single little “s” at the end of their name. That, my friends, is the main cause behind many debugging hours which end up with “damn! there's an s there!”.

To avoid it I set a rule -

When dealing with collections I use the plural form, e.g. items, but when dealing with a single item I name it singleItem.

This really helps me tell right away which is which. Again, it might sound petty to you but this little change will do wonders to your code readablity :)

Functions

Functions are a key aspect of the language I’m practicing these days, that is JavaScript, and this requires me to treat their names with extra respect.
Same as with variables, function names should state what the function does, and so my first rule is -

If it is hard to find a name which defines what your function does it usually means that your function does too much and needs to be broken into smaller functions (extract function).

The “This and that”

Sometimes the name you instinctively give a function may alert you that your design is a bit “smelly”.
If your function name has “and” in it, e.g. seekAndDistroy(), in most cases it means that this function is doing 2 different things and therefore should be extracted into 2 different functions, e.g. seek() and destroy() and call them one after the other or when needed, have the flexibility to call one of them without the other.

Getter Functions

I’m not referring to the getter methods of an Object here, rather to functions which return a certain value according to their arguments. Their name should obviously state their purpose, so the verb “get” should be there, e.g. getItemById(id).

A function which has a name with “get” in it should always return some kind of calculated value.
I try to avoid alternative verbs like “fetch”, “retrieve”, “obtain” etc. when there is no need for them, just to keep my code consistent and my colleagues' mental health at ease.

Wrapping up

Paying attention to how we name the key aspects of our code is a well worth investment. Giving suitable names which clearly define the purpose of a variable, a function, a file etc. will save a lot of time later on, both in debugging or maintaining it.
As always if you have any ideas on how to make this better or any other approaches, be sure to share with the rest of us!

Hey! If you liked what you've just read check out @mattibarzeev on Twitter 🍻

Photo by Raymond Rasmusson on Unsplash