Variable Names

I wrote this on today in a thread which was discussing short variable names:

My own take on variable names is that naming is one of the hardest problems in software development, and that the length of a variable name should reflect the length of the scope in which it is visible. A single letter variable name is fine in a small loop, for example. A larger scope would call for a correspondingly larger variable name.

The rationale for this is that our short-term memory can store only a small amount of information; 7 ± 2 items according to Miller, but more recently thought to be 3 or 4 "chunks". When reading or writing code, additional text such as unnecessary comments, excessive punctuation and even long names can obscure the meaning of the code making it harder to reason about. If a common variable in a small scope can be given a short name, that variable and its purpose can be stored in our short-term memory for the duration of our concentration on that scope. For larger scopes, where there are more names, this would overflow our short-term memory requiring us to go back and check what the short name actually referred to, negating the benefit of having less cluttered code.

Naturally, this is also the reason why the name must be descriptive rather than merely long, and certainly shouldn't be misleading.

And as with other names, a single letter variable name should reflect its purpose as much as possible, to further aid our understanding; $q for a queue, $c for a customer, $n for a count and so forth. The problems start to occur when we have a customer and a context, for example, and at that point having a variable named $c is more of a hindrance than a help. That's when you would want $cust and $cxt, or $customer and $context depending on the size of their scopes.


Hi Paul

Hmmm - A complex and tricky topic.

Several things guide my choice of names:

  • Short for loops, e.g. $i, especially for array indexes. Agree with you there.

  • Long, meaningful ones almost everywhere else. It takes time to type them, so copy-and-paste is common. I wish modern editors automatically remembered the last word you typed, so I could hit a key to say 'Save this word!' And later hit another key to save 'Recall that word!' rather than having to back up the cursor and mark the word. Padre programmers - Are U listening :-)?

  • After decades of programming (not just me) I'm convinced the format $verb_$noun is the best way to name things, e.g. save_file, etc, etc. But I had to train myself to do that consistently, and I still see people naming differently, and it jars every time.


About typing long names: any decent editor should have some completion feature. I don't know about Padre, but in Emacs you can press M-/ and Emacs will complete any word for you.

new programmers possibly also tend to avoid long variable names because they end up writing them more often than more experienced coders (who will use Perl-isms like 'my $var = fn() or return;' rather than three separate lines for 'my $var', assigning the value, and then testing the value.

I'd say there comes a point where the effects of syntactic conventions are rendered practically negligible in comparison with the difficulties in understanding how the observable states in the operational code are related. Any code that does complicated things will require effort to understand irrespective of how it actually appears in your editor.

For my money if you can figure out the intent of the author (which may of course be yourself a few iterations previously) you at least have a base to explore from. So for me long variable/sub-routine names and voluminous comments might be irritating to look at, but they do provide clues to the context in which the code was written.

As a loose approximation to literate programming I've taken to keeping separate journal .pod's for my more involved code bases. It can be instructive to see how much background thought goes into a few lines of code, and it does make evolution of the code more informed, if not demonstrably more efficient. Others who have picked up the code have also commented that having some idea what I was thinking does help in making sense of the code.

Like the rest of us, I guess, I'd all like the code to speak for itself, with all unnecessary ornamentation stripped, in the manner of an elegant mathematical proof. However to understand a proof you have to understand the mathematical context, and the context of a piece of software is usually (nearly always?) far less rigidly constrained than the mathematics behind a proof.

Leave a comment

About Paul Johnson

user-pic I don't really blog about Perl.