Naming your variables!
By: Taohidul Islam
Tags: Function, Best Practices, Programming, Conversion, Variables

As you know, naming is very important in software development. We name our variables, functions, classes, packages etc. Here, we’ll discuss about some common conventions of naming in programming.

You may write a code once, but it is read repeatedly. So spending time in writing good code actually saves your time directly and indirectly!

Purpose of variable should be clear

A variable’s name should express the intention (cause of uses) of the variable. Let, we have a variable named t which stores time. But look, here t reveals nothing about its usage. If variable’s name expresses about its measurement and unit then it can be more clear. The following variables’ intention are more clear than t :

elapsedTimeInDays , daysSinceOpenning , daysSinceClosing, personAgeInDays

It’s better choosing names that reveal the intent, which can make it much easier to understand and change code.

Can you guess the purpose of this code?

It is hard to guess what this code is doing, right? But why?There are no complex expressions. Also spacing and indentation are reasonable. There are only some variables and constants mentioned. There aren’t even any fancy classes or polymorphic methods.

The problem isn’t the simplicity of the code but the implicity of the code! :P Because of implicity we don’t know the answer of following question:

What kinds of things/values are in theList ? What is the significance of the zeroth index of an item in theList ? What is the significance of the value 4 and why are we using 4 here? What are the values returned using list1 ?

The answers to these questions are not present in the code sample, but they could have been.

Let, we’re working in a mine sweeper game. We find that the board is a list of cells called theList . Let’s rename that to gameBoard . Each cell on the board is represented by a simple array. We further find that the zeroth subscript is the location of a status value and a status value of 4 means flagged .

Just by giving these concepts names we can improve the code considerably:

Notice that the simplicity of the code has not changed but it’s more explicit now! It still has exactly the same number of operators and constants.

We can go further and write a simple class for cells instead of using an array of integers. It can include an intention-revealing function (call it isFlagged ) to hide the magic numbers.

With some simple name changes, it’s not difficult to understand what’s going on. Feel the power of choosing good names!

Avoid misinformation

Programmers should avoid leaving false clues by their variables’ names. It makes a program ambiguous. We should avoid words whose entrenched meanings vary from our intended meaning.

For example, we want to store account information of a bank customer and the information is not in a list but if we use accountList variable to store the value then it won’t give the appropriate indication. We should not append the word “list” after any variable’s name unless it’s actually a List .

Now, if we want to store many accounts to a container and accounts can be of any (container) types (like list , queryset , array etc.) then it is better using accountGroup or bunchOfAccounts as variable’s name.

Two variables whose names differ in small portion also may confuse you.

Let, testVariableNameFromClassA , testVariableNameFromClassB these two are valid variable, but it is easy to make interchange them mistakenly.

Also auto code completion feature of modern IDEs can increase your pain!

One of the common issues of new programmers is using single character like O or o , lowercase L ( l ) as name. This may cause serious problem while debugging.

As you see, this code is ambiguous enough to confuse you!

Variable’s name should have meaningful uniqueness

A variable’s name should express its purpose and meaning clearly.

Feel the difference between readability of the following code snippets :

Let, you have three functions :

getActiveCustomer();

getActiveCustomers();

getActiveInfo();

Can you guess the purpose of every function? It’s tough to guess which function to call on which purpose. This is the power of ambiguity! :P

Names should be pronounceable

Humans are good at words. Anything well pronounceable is easy to catch.

Let, we have a function named getDMY() which returns day-month-year of a schedule. Suppose, you need to describe your code to someone. Now, what will be the pronunciation of getDMY ? Confused, YES?

Renaming it to getDayMonthYear() can solve your problem instantly!

Size of variable’s name and searchability

Variable’s name should be of moderate size (not so long or not so small, it’s just trade-off depending on context). Shorter names are generally better than longer ones, as long as they are clear. But for clarity names can be longer.

Length of variable’s name should correspond to the size of its scope.

A single-letter name should only be used as local variable inside short methods/functions.

Traditionally, we use i , j or k (caution : not l or o ) for loop control if its scope is very small .

I personally prefer not using single letter variables (except : small scoped loop).

A name should be easily searchable and replaceable.

This code is ambiguous too. If we want to replace 50, 4 or 5 then it can be too painful. Because there may be more constants of same value in the code and those can be replaced mistakenly.

Look at this code, we can easily search constants by related variable’s name and replace them.

Class names and method/function names

Class name and object name should be noun or noun phrase (like : User Customer , Account etc).

You should avoid words like Data , Information or Info (They don’t give clear explanation of class or object. There can be different types of data or information).

A verb as class name is highly discouraged.

Method/function name should be verb or verb phrase (like : delete, save, post etc).

Setter methods should be prefixed with set and getter methods should be prefixed with get .

* * * Some life saving short notes

“Say what you mean. Mean what you say” . (Everything should be clear. No ambiguous assumption should be made)

Use one word for only one single purpose/concept. Using a single word for different purposes may confuse you.

Names should be easily memorable.

Names should be distinct.

Courtesy

Some of the examples of this article are taken from Robert C. Martin’s awesome book Clean Code .

Conclusion

Good description skill helps in good naming. By practice, it gradually gets developed day by day.

You can also read :