How to engineer good variable names

Let’s look at some techniques that will help make your code more readable, maintainable and ensure you don’t look back at it in 3 to 6 months and wonder who wrote it and what the world they were thinking. With all that squared away, let’s look at variables and how to use them to work in our favor.

Variable Names

When you’re reading your code, you may not notice but the only things that are really user-defined are the variable, project/package and method names. Everything else is either a literal, keyword or syntactical construct for your chosen language. Say What? Yeah, check it out:

// C#

public class Hello 
{         
    public static void Main(string[] args)
    {
        string myVariable = “Hello World!”;    
        System.Console.WriteLine(myVariable);
    }
}

Without breaking this thing down line by line, suffice it to say that “HelloWorld” on line 1, “Hello” located on line 3, “Main” on line 4 and “myVariable” on line 5 are the only things you have the ability to name as you please. Everything else is a keyword (namespace, class, static, …) a terminator (;) or a construct of the language (parenthesis, brackets, braces, quotation marks)

What’s my point? All of the keywords and semi-colons and stuff that don’t change become second nature and they start to really stick out as you gain experience. You really get to the point where you know the keywords and where they should be.

One thing the books teach is that your code needs to be self-documenting. Variable names help with this. Let’s look at an example:

// C#

public class Hello 
{
    public static void Main(string[] args)
    {
        string myVar1 = “Jane Smith”;
        string myVar2 = “John Smith”;
        string myVar3 = “James Smith”;
        OutputName(myVar1);
        OutputName(myVar2);
        OutputName(myVar3);
    }
    private static void OutputName(string name)
    {
        System.Console.WriteLine(name);
    }
}

Pretty straight forward right? Well, not so fast. Let’s look at those variable names: myVar1, myVar2 and myVar3. If I were reading this in a code review, my first thought would be, “Well how do you keep them separated later?” Sure, when you create them and use them one time in a simple example like this, they make sense. But what about when your code gets a little longer and the variables are passed around and manipulated by your program? You really will find yourself scrolling back through and reading every line trying to determine what the difference was between myVar1 and myVar2. You’ll be wondering which one you should be using as certain inputs to other functions and why you chose such a crappy variable name to begin with. Without scrolling up, which one was John?

A better approach would be to give them all separate names. Let’s look at that.

// C#

public class Hello 
{         
    public static void Main(string[] args)
    {
        string nameForJane = “Jane Smith”;
        string nameForJohn = “John Smith”;
        string nameForJames = “James Smith”;
        OutputName(nameForJane);
        OutputName(nameForJohn);
        OutputName(nameForJames);
    }
    private static void OutputName(string name)
    {
        System.Console.WriteLine(name);
    }
}

With this approach, we’re now able to distinguish the difference between Jane, John and James everywhere in our code, just by looking at the variable name. Also, instead of myVar1, which has no explicit meaning, our code becomes self-documenting. We know that the variable nameForJane is a variable that holds the value of the name for Jane. No need for comments, no need to go back and look. Let’s also take the following snippet into consideration:

// C#

string nameForJane = “Jane Smith”;
nameForJane = “John Smith”;

I hope you see from this example that variable names are really important. Specifically, why would you set the nameForJane variable to “John Smith”? Does that even make sense? Maybe it does in the particular case you’re working on, but it certainly doesn’t make sense here.

Are there any rules for naming variables? Maybe not rules, but each language typically has its own best practices. Further, the company or project you are working on may have guidelines that overrule the language’s. I’ve seen several different formats throughout the years. Let’s look at some for future reference:

Notation Name	Variable Name
Flat Notation	thisismyvariable
Pascal Notation	ThisIsMyVariable
Camel Notation	thisIsMyVariable
Kebab Notation	this-is-my-variable
Snake Notation	this_is_my_variable
Macro Notation	THIS_IS_MY_VARIABLE
Cobel Notation	THIS-IS-MY-VARIABLE
Hungarian Notation	typeThisIsMyVariable

Yeah, some suck worse than others. If you need additional information on any particular notation, search for the name of the notation I have listed above (ex. Hungarian Notation). If you’re unfamiliar with your programming language’s naming conventions just do a quick search for “naming conventions for [LANGUAGE]” and you’ll find it in the documentation. If you’re new to a company, ask your supervisor if there is a specific format you’re supposed to follow. Even when you start working on a new project, ask the lead if there’s a particular naming convention you should follow. I’d say 90% of the time, the answer is going to be to stay consistent with the existing code.

I really hope you found this information useful. This is certainly not all there is to cover on variable naming conventions and best practices. We can revisit this when we talk about other advanced concepts where choosing a variable name is important. We’ll look at method names in the next post.