"Crummy Variable Naming Not Restricted to Lousy Source Code" by jerryk

Mon, 11 Sep 2006 08:56:00 PDT

Have you ever tried to read source code littered with variables that have undescriptive names like i, ii, i0, ii0, temp, temp1, temp2, and so on? Such names are arguably concise and tolerable in some circumstances such as when:

The symbol is being used for something of very low conceptual weight, e.g. an index of iteration that’s no more than a dummy variable that hardly deserves a name, and whose purpose is little more than walking over some simply indexed set of values.
When the use of the symbol is highly local. Hopefully its scope is restricted to the body of a small loop, or other relatively compact code block, and it’s not even visible outside of it.
When in some other context, hopefully widely known by your audience, those symbols are universally used as you’re using them. Denoting coordinates in the plane with variations on x and y is probably familiar to everybody. In other cases you may want to be more explicit and careful.

When variables with ultra-terse, non-descriptive names are used in the absence of these conditions, code gets much harder to read. Its meaning is less clear on initial inspection, and maintaining a sense of it burdens the working memory of the reader.

It turns out that annoying source code isn’t the only place this happens. I was recently reading something, which will be left unnamed to protect the guilty, that contained roughly the following passage:

The system has three eigenvalues: one positive, one zero, one negative. Let us call them alpha, mu, and upsilon respectively.

Alpha, mu and upsilon? WTF, man? Are you trying to annoy the reader, when five pages from now, you next refer to these quantities? Here’s a suggestion! Why don’t we assign the one with value zero the convenient name “zero?” I vaguely remember that the Arabs of antiquity even provided a convenient notation for this quantity. I believe it was some kind of circle. It’s an amusing exercise to come up with less useless names for the other two eigenvalues.

And lower-case upsilon? Maybe there’s a reason people often avoid using that particular letter in written mathematics… especially in handwritten mathematics? Seeing a whiteboard full of sloppily rendered u’s, v’s, upsilons, and the uppercase counterparts of the first two is a strong predictor of a plunge into the dunk tank of tortured exposition.

But what do I know? I just write one cranky post every three months, and it’s generally devoid of u’s, v’s, upsilons (to say nothing of interesting content).

Obscurata Craptacula comments on Crummy Variable Naming Not Restricted to Lousy Source Code

"Crummy Variable Naming Not Restricted to Lousy Source Code" by jerryk