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.
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:
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).
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.
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).
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.
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.
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.
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.
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.