Code Design - Meaningful Variables Names
Tags: javascript, codequality, productivity
Published: 2020-06-03 03:32:57

> _"You can’t give a variable name the way you give a dog a name"_ - Steve McConnell

We, developers name everything from variables, functions, classes to files, however many times we focus on solving a problem and we do not worry about readability and best practices while naming.

Variable naming is an important aspect in making your code readable so, you should follow a simple idea: **Create variables that describe their function.**

Choosing good names takes time but often saves more than it takes. This is important because when you write code, you must keep in mind that other developers will read, and they will need to understand what you write. Our code must be a well-written story and like a good one should be easy to read and understand, it must expose the tensions in the problem to be solved.

There are some practices which in my opinion are important.

##Avoid Disinformation
We must avoid leaving false clues that obscure the meaning of code. Avoid words whose meanings vary from our intended meaning. Do not refer to a grouping of orders as an `orderList` unless it is actually a `List`. The word `List` means something specific to programmers specially in Java, just plain orders would be better.

##Use Pronounceable Names
If you cannot pronounce it, you should not name it that way. This matter because programming is a social activity and if you use unpronounceable names you will not be able to discuss your code without sounding like an idiot. "Well, over here on the arr vtr has three cee and two enn and we have to add a new kyew, see?"

##Use searchable Names
Single-letter names and numeric constants have a particular problem since they are not easy to locate across a body of text. The name `e` is a poor choice for any variable for which a programmer might need to search. Single-letter names can ONLY be used as local variables inside short methods, specially short for loops.

##Pick One Word per Concept
Pick one word for one abstract concept and stick with it. For example, it’s confusing to have `fetch`, `retrieve`, and `get` as equivalent methods of different classes. How do you remember which method name goes with which class?

##Avoid Encodings
Encoding type or scope information into names simply adds an extra burden of deciphering. It hardly seems reasonable to require each new employee to learn yet another encoding "language" in addition to learning the (usually considerable) body of code that they’ll be working in. It is an unnecessary mental burden when trying to solve a problem. Encoded names are seldom pronounceable and are easy to mis-type.

Let´s see an example. With out context, can you spot what this code is trying to do?

```javascript
var theList = [{ id: 1001, sent: false, territory: 'it' }, { id: 1002, sent: true, territory: 'sp' }, { id: 1003, sent: true, territory: 'sp' }]

function getThem(territory) {
  var list1 = [];
  for (let x of theList) {

    if (x.sent === true && x.territory === territory) {
      list1.push(x);
    }
  }
  return list1;
}
```

Is it hard to understand what this code is doing right? What do `theList`, `list1`, `getThem` mean? As you can see those variable’s name do not fully describe the entity they represent. The problem isn’t the simplicity of the code but the **implicity** of the code. The answers to these questions are not present in the code sample, but they could have been.

Let’s say that we are working in a company which ships orders of products. We noticed that the orders is an array called `theList`. Let’s rename it to orders. We further noticed that the every order contains an `id`, `sent` and `territory` attribute, we can change `shipped` instead of `sent` and `country` instead of `territory` since they infer common concepts of delivering products. 

```javascript
var orders = [{ id: 1001, shipped: true, country: 'it' }, { id: 1002, shipped: true, country: 'sp' }, { id: 1003, shipped: true, country: 'sp' }]
```

Better, right?

What about the the `getThem` function, basically we want to retrieve those orders which were shipped in a specific country, so why not to call that function `getShippedOrdersByCountry` readable right? 

`list1` doesn’t say anything, we can change its name by `shippedOrders`. What about the for loop, we are lopping an array of `orders`, so one of object of it represent an `order`.

```javascript
function getShippedOrdersByCountry(country) {
  const shippedOrders = [];
  for (const order of orders) {
    if (order.shipped && order.country === country) {
      shippedOrders.push(order)
    }
  }
  return shippedOrders;
}
```

What else can we improve? Of course, that for loop.

```javascript
function getShippedOrdersByCountry(country) {
  return orders.filter(order => (order.shipped && order.country === country));
}
```


##Bibliography

McConnell, S. (2004). _Code Complete_ (2 ed.). Washington, United States of America: Microsoft Press.

Martin, R. C. (2009). _Clean Code_. Boston, United States of America: Pearson Education, Inc.