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.