Code Design - Meaningful Variables Names

"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?

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.

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.

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.

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.