Naming matters

Naming your code correctly can save you and your colleagues a lot of time. here’s how…

Whether it is variables or functions, naming has a crucial part in debugging and understanding code, and since we spend more time reading code than writing it, it’s important that we pay attention to this (somewhat neglected) aspect of coding.
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 my practices and code naming rules of thumb.

Variables

Generally speaking…

Everybody create variables, but very few take the time to really name them correctly. The reasons for it may vary but mostly it’s because we wanted to check something’s working really fast and left that “t” variable there to puzzle future maintainers (usually ourselves).
My rule of thumb on this matter is -

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

and that does not mean what type the variable is. I don’t 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 the code you maintain where a variable was misleading and made you go astray logically.
You will read this variable name over and over for many times so you might as well set it to help you. If we dive a little deeper there are rules I follow which relate to the type of the variable:

Booleans

The rule here for me is quite simple and straight forward —

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 a straight forward variable names, such as “isInFastMode” in the view scope or “hasItems” in the object scope. I consider the alternative “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) than the developers crocked English syntax 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 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 telling right away which is which. Again, it might sound petty to you but aside from optimizing your code performance you should also take care of optimizing your code readability speed, and this does just that.

Functions

Generally speaking…

Functions are a key aspect of the language I’m practicing these days, that is JavaScript, and this requires me to treat their name 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).

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 things

And therefore should be extracted into 2 different functions, e.g. seek() and destroy() and call them one after the other or even better, obtain the flexibility to call one of them without the other.

Getters Functions

Unlike the a getter on an JavaScript Object, this one refers to functions which return a value according to an argument or two. Their name should obviously state their purpose, so the verb “get” should reside 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 the life of the one reading it easier.

Files

Generally speaking…

File names help a lot to indicate what is defined within that file. Given that you are not defining multiple module inside a single file, knowing a file name can pretty much give you a good idea about its content.
So there is not much about it —

If the file defines a view I will indicate it in its name, e.g. “items-list-view.js”

Some may not agree with this approach, but I found it very comfortable for later searches.

Test Files

Although test files are not bound to the code they test, I try to align them both by their names. So if for example I have an “items-list-view.js” files which defines a… (well you can tell what it defines, right ;) then the corresponding test file will be “items-list-view.test.js” (or "items-list-view.spec.js"). This creates pairs of files, one is the source and the other is the test. The result is a fast way to know if a certain module has tests or not.

conclusion

There are more examples that I’ve probably forgot, but the point I want to make is that paying attention to how we name the key aspects of our code is an investment worth our while. Giving suitable names which clearly define the purpose of a variable, a function or what-have-you can save a lot of time later on, whether it’s debugging or maintaining it.