- notoriousb1t

When debugging code, it is incredibly important that variables make sense as soon as you look at them. The less you get derailed, the fewer hours you waste getting into the zone.

Descriptive Variables

As my brain is building up this block tower of variables, functions, and classes, the last thing I want to happen is for that tower to get knocked down by a variable named it. What exactly is it?

Well... hmm... what does this do?

    function action() {
        var C1 = "\u0062";
        var C2 = "\u0065";
        var C3 = "\u0074";
        var C4 = "\u006E";
        var C5 = "\u006F";
        var C6 = "\u0072";

        var a = C1 + C2;
        var b = C3 + C5;
        var c = C5 + C6;
        var d = C4 + C5 + C3;
        return [b, a, c, d, b, a].join(" ");
    }

I wrote the above code, and it still took me a few seconds to figure out what I was even looking at. Let's try that again with more descriptive variables.

Contrived, but better

    function hamlet() {
        var B = "\u0062";
        var E = "\u0065";
        var T = "\u0074";
        var N = "\u006E";
        var O = "\u006F";
        var R = "\u0072";

        var be = B + E;
        var to = T + O;
        var or = O + R;
        var not = N + O + T;
        return [to, be, or, not, to, be].join(" ");
    }

That was way easier to read. I can clearly see that this function returns (in a roundabout way) one of the most well known lines from the Shakespearean play, Hamlet.

Variables.. In English

In addition to making variables descriptive, it is important to use common words. If you use words that are uncommon or use phrases that are awkward, the next person will have a bad time. Reading code shouldn't feel like reading Moby Dick. It should feel like reading a grocery list.

Pretty Murky

    var seriesOfCharacterMatches = { /* ... */};
    function findFirstSeriesOfCharactersMatch(seriesOfCharacters) {
        return seriesOfCharacterMatches[seriesOfCharacters];
    }

Much Clearer

    var thesaurus = { /* ... */ };
    function getSynonym(word) {
        return thesaurus[word];
    }

What's another word for Thesaurus? -- Steven Wright

Using common language results in much more readable code. Instead of trying to describe the attributes or behaviors of the object, try to use nouns. If you've already used the word, pull out a thesaurus or ask someone, even a non-developer, for a synonym.

Use Suffixes over Prefixes

Using suffixes is particularly important when dealing with visual components or controls. I'm talking about Swing, WinForms, WebForms, and the like. When using these controls, you are often buried in code that lays out the view, so it is easy to lose track of where you are.

Prefixes

    var isAdmin = Roles.IsUserInRole("Administrator");
    lblInvoiceNumber.Visible = isAdmin;
    txtInvoiceNumber.Visible = isAdmin;
    lblIsAllowed.Visible = isAdmin;
    chkIsAllowed.Visible = isAdmin;
    lblStatus.Visible = isAdmin;
    ddlStatus.Visible = isAdmin;

When using prefixes, you have to first think of what type of control it is and then look through those types of controls to find the name of the value you seek.

Suffixes

    var isAdmin = Roles.IsUserInRole("Administrator");
    InvoiceNumberLabel.Visible = isAdmin;
    InvoiceNumberField.Visible = isAdmin;
    IsAllowedLabel.Visible = isAdmin;
    IsAllowedCheckbox.Visible = isAdmin;
    StatusLabel.Visible = isAdmin;
    StatusDDL.Visible = isAdmin;

When using suffixes, you can start typing the name of the value instead of worrying first about what type of component it is stored in. In my mind, this is more intuitive. Also, do you see how nicely those controls are grouped? In my opinion, using suffixes also result in more elegant code.

Exceptions

There are some cases that the above guidelines would be confusing... where the ideas above would completely go against the natural way of writing a language. Please ignore the above in the following circumstances:

If it's used for flow control

    for (int i = 0; i < values.length; i++) {
        // do something with values[i]
    }

People aren't used to seeing the whole word index in a loop. Using i or x is typical for holding the current index. I don't recommend trying to use full names for clarification. I think it will make your code less readable.

If it's a simple lambda

        var numbers = (new [] { 4, 5, 6, 7 })
            .OrderBy(i => i)
            .Select(i => i * i)
            .ToArray();

In most languages, it is typical to use single letter variables when defining simple lambdas. You might raise some eyebrows for using full variable names, so it is probably better to stick to short names. I recommend using one to four letters for lambda variables. For example, ctrl => ctrl instead of c => c. The code ctrl => ctrl hints that the variable is a control without being too verbose.

In simple cases, it makes sense to use the single letter. However, in complicated queries in ORM logic you might want to bump it up to three or four letters. I typically need to do this when grouping then flattening a sequence of objects since the type of the variable becomes less obvious.

If it's abstract or generic

    function(a, b) {
        if (a < b) {
            return -1;
        }
        if (a > b) {
            return 1;
        }
        return 0;
    }

Sometimes, the variable isn't referring to any particular type or any particular object. You see this most in comparators of sorts. The variables a and b aren't any particular type of object. The only requirement for the above code to work would be that the two can be used with less than and greater than. Attempting to find descriptive names would probably end up being confusing.