Finding variables like finding books in messy bookstore. (Image by Darwin Vegher)

Variables: How not to suck at naming them?

Have you ever start thinking ‘How do I name this variable so that other engineers can understand them easily?’ while writing your code? If you do, you’re not alone. If you don’t, chances are your variable naming might suck.

Take the following snippet as an example:

const data = req.body;
let i = data.obj.length;
while (i > 0) {
  const temp = data.obj[i].new_field;
  data.obj[i].new_field = temp + ' (Updated)';
  i--;
}

Can you tell what the above code do? Can you tell what each of the variables are for? If you were to review this code, you will have a hard time to understand what each of the variables are supposed to do. Even as an author, you will likely to forget what it does a few days after your commit of the code.

It get worse if you are dealing with formulas and numbers. You might’ve written a code that look somewhat like the following:

let x = 3.25;
let y = 5;
let x2 = 3.25 * 5;
let xy = x * y;
if (y > 5) {
  // Do something
}

These kind of variable naming will make it nearly impossible for someone in your team to understand your code when they are trying to debug or review, which can be costly because another engineer might need to refer to the author for an explanation into the code or worse, the author might need to take some time to read through the code before explaining it to the engineer.

The Conventions

1. Use proper words.
2. Avoid numbers.
3. Avoid single character.
4. Avoid naming variables that resemble each other.
5. Read your variable in a sentence.

With all these conventions in mind, your variable should be something like the following:

let pricePerUnit = 5.5;
let totalUnitBought = 5;
let conversionRateForUSD = 4.1;
let totalPrice = pricePerUnit * totalUnitBought;
let totalPriceInUSD = totalPrice * conversionRateForUSD;

You can now read the code like this:

1. Let price per unit equals to 5.5.
2. Let total unit bought equals to 5.
3. Let conversion rate for USD equals to 4.1.
4. Let total price equals to price per unit multiply by total unit bought.
5. Let total price in USD equals to total price multiply by conversion rate for USD.

Avoid variables like num, avg, val, x, y, total. All of them don’t mean anything and as a reader, it’s hard to understand a piece of code when looking at the variables is like being in an unknown territory.

Let’s go back to the initial code and fix the problem. We’ll keep in mind all the conventions for naming a variable, and it should look somewhat like the following:

const { products } = req.body;
const totalProducts = products.length;
let currentProductIndex = 0;
while (currentProductIndex < totalProducts) {
  const initialProductTitle = products[currentProductIndex].productTitle;
  products[currentProductIndex].productTitle = initialProductTitle + ' (Updated)';
  currentProductIndex++;
}

Or better,

let { products } = req.body;
products = products.map((product) => {
  const initialProductTitle = product.productTitle;
  product.productTitle = `${initialProductTitle} (Updated)`;
  return product;
});

Now we can understand and see clearly that the code is appending a string to the existing product title in a list of products object.

Conclusion

In this short article, we’ve covered how to name your variable while ensuring others understand its meaning and usage. Keep the 5 conventions in mind while declaring your next variable, it should keep you in a good hand. Speed is one thing when writing code, however, readability and understandability is another thing you have to keep in mind. No matter how you write your code, always make sure to keep it consistent throughout your application.

If you notice I didn’t talk about using camelCase or snake_case in the article, that’s because it is totally up to you which one you choose for your application. As long as you keep it consistent, your codebase should be easier to understand by a few degree.

Is there anything that I’ve missed? Anything you don’t agree with? Let me know in the comment section and let’s discuss. Cheers! :)