
A Guide to Naming Variables - pacaro
http://a-nickels-worth.blogspot.com/2016/04/a-guide-to-naming-variables.html
======
rectang
Most of this, even if it's not my preference, I would never bother arguing
with. But I have a question about a practice that is tremendously widespread.

I have real trouble with single-letter variable names like "c", for any
function more than, say, 2-3 lines. I scan the code and it _increases_ my
mental load because I have to remind myself what it means.

Obviously a lot of people don't have problems with this, but I do. Anybody
else?

Maybe it's because I jump around a lot from function to function?

~~~
logicallee
it's obvious that computer scientists have COMPLETELY dropped the ball by not
figuring out a way for anyone to write "it", "that", "which" and so on and
have the IDE and language disambiguate it into what you were JUST talking
about. This is stuff that my great-grandparents should have been suggesting
some time after Ada Lovelace wrote about the analytical engine in 1842 or
1843. Not something I should be writing about in 2016. Yeah, okay, before
always-on Internet it might make sense to have a small, unambiguous, self-
contained grammar. The same is not true in 2016.

Here's how you calculate the absolute value of an integer: -> "if it's non-
negative, return it; if it's negative return its opposite".

Here's how you calculate the absolute value of an integer if you're using any
programming language written in 60 years: -> "if (argument <= 0) return
argument; else return argument * -1." (or some variation)

There is literally no way to refer to "it" instead of "argument" except by
changing "argument" to read "a" (or "i" or "x" or "$_" or...)

My point is that it's literally impossible to write "if (it > =0) return it;
else return (it * -1)" if you've just mentioned "it" and you are there to
check and correct the IDE if it's wrong. (Oh, wait, I should write "to correct
the IDE if the IDE is wrong.")

I bet 90% of human languages have a way to refer to something you've JUST
mentioned without repeating a word for it. (Words like it, that, etc.) I bet
0% of computer languages let you write "it" for the last thing you just
referred to, even if there is literally 1 choice in the whole function, as in
my absolute value example.

Ridiculous!

~~~
ArkyBeagle
"Computer scientists" don't have an opinion much about _a_ particular IDE; if
you want that functionality in an IDE, it might be a shorter path to cause it
to exist in the first place.

I bet it's harder than you think.

Also, IDEs are better than they used to be - I stopped using them because they
caused problems in the late 20th Century. There was a proliferation of them
until Eclipse got good enough to not cause problems. Eclipse still had less
text editing power than some just-plain-old-editors from the 1980s. So I only
use an IDE if it's the only logical choice for a development system. It
usually isn't.

If, as in one shop at which I worked, you constantly write, say EMACS macros
and use them a lot, you will evolutionary drift away and it will make your
team more and more ... linguistically isolated, which has costs in onboarding
and this sort of mild narcissism about _your_ setup.

I think that dependence on an IDE is mostly a weakness, not a strength.

~~~
logicallee
That is fair. I don't have a specific suggestion on how to implement it, which
layer (language, IDE, some connected service) or where to do it. I just know
that current coding practice _must_ be wrong.

~~~
ArkyBeagle
If that's the worst thing you see, please consider being grateful :) It could
always be worse.

------
mixmastamyk
A good guide, but I didn't like this part:

    
    
        Avoid Over-used Cliches
    
        In addition to not being Teutonic, the following variable names have been
        so horribly abused over the years that they should never be used, ever.
    
            val, value
            result, res, retval
            tmp, temp
            count
            str
    

Cliches? If you are trying to communicate, these names are well known ways to
do that. If there is something more specific to put in there, by all means,
but I often find these names useful, combined with a good function name and
docs of course. Thoughts?

~~~
Niksko
I guess what he's getting at here is that these variable names don't convey
what the variable holds.

Let's say you're writing C and you want to return status information from
processes as integers. Instead of:

> return retVal;

where retVal could be 0, -1 or -2 to indicate success or failure of the
function, how about:

> return functionStatusCode;

? Or be even more specific (let's say the function tried to parse some text)
with parserStatusCode.

All of those are more helpful than retval, because they give you some sort of
idea as to what you're returning. You'r enot returning how many values were
parsed, or some sort of information about what you parsed, you're returning
the status of the parsing function.

The meaning of those values is probably a little harder to encode in the
variable names (especially if there are many such values), but that's what the
comments are for.

~~~
Roboprog
How about just "status" for the return code var name? It should be readily
apparent that the var is "my" (the routine's) status [code].

~~~
Niksko
Ok, the 'function' part is not useful. And perhaps C was a bad example.

Let's say it's Python now, and for some reason I'm still returning 0, -1 or
-2. Then 'statusCode' would be a good name for the variable I guess. The code
part indicates that it's a codified version of the status. The smarter way
might be to just return a status object or something, in which case perhaps
'statusObject' is better? Not sure.

I guess one thing I took away from the article is that it would be nice to be
able to encode _how_ the data is being returned in the name of the return
value. This saves me going and finding when the variable was created to get
its type, or when the variable was assigned to.

~~~
Roboprog
I'm OK with the "one word" parameter / return value names, in part, I guess,
because I'm also a big proponent of a "pro forma" comment banner for every
routine. For simple things, the comment can be a one-liner ("Return thing X"),
but otherwise, explain each param and the return value.

Now, if the internal variables require a "data dictionary" level set of
comments, that's another matter. Something is (usually) wrong in that case.

------
wyldfire
No mention of physical units? I always find it terribly frustrating when
trying to read code that talks about physical dimensions like time and space
without any clue as to what we're measuring.

    
    
        const int timeout = strtol(argv[2], NULL, 10);
        send_and_waitfor(&msg, timeout);
    

When I read this code, should I take for granted that the caller and callee
are using the same order of magnitude that's intended?

If instead I see

    
    
        const int timeout_ms = strtol(argv[2], NULL, 10);
        send_and_waitfor(&msg, timeout_ms);
    

then I can quickly audit whether the inputs and outputs actually preserve the
convention.

~~~
Stasis5001
If possible, it's much better to handle physical units with the type system.
If your timeout is a timedelta class (or duration/difftime/interval etc.),
then this whole issue disappears.

------
Roboprog
Bit of a tangent, but here goes...

It's a shame that C ... Java like languages became dominant, in that they
"hide" identifier names _after_ the type types, rather than putting the
identifiers at the start of a line where they are more visible. (thank God for
type inference, I guess, in newer languages)

Also, I find CamelCraps an impediment to scanning the names in code, as well.
This is less of an issue when the name is one word, but "we" sure seem to like
our AdjectiveAdjectiveAdjectiveNoun names in Java-land :-(

E.g. -

    
    
        qualifier qualifier AdjectiveAdjectiveAdjectiveNoun adjectiveAdjectiveAdjectiveNoun = new AdjectiveAdjectiveAdjectiveNoun(42)
    

Or was I supposed to @AutoInject that?

Please, just shoot me now.

------
codesnik
"rather than the elliptical vagueness of Romance languages like English" \-
what?

~~~
theandrewbailey
I had a few problems with that, too. English isn't a romance language (it
stole a lot of romance vocabulary, though). I guess that the author eventually
gets around to explaining what he means: too much vocabulary that doesn't
break down into simpler, understandable words. It reminds me of the linguistic
contortions you need to do in order to write like the Thing Explainer.

~~~
fourthark
Me three. I guess it's better said that those borrowed words don't break down
easily for native speakers of English. There may be more concise ways to
assemble variable names in Romance languages if you're a native speaker.

------
kogus
Good advice. If this sort of thing is appealing to you, then read Code
Complete by Steve McConnell. It's basically an entire book full of very solid
advice of this sort.

~~~
gbhn
Another book you'll enjoy if you liked this post: "The Art of Readable Code"
([http://www.amazon.com/Art-Readable-Code-Theory-
Practice/dp/0...](http://www.amazon.com/Art-Readable-Code-Theory-
Practice/dp/0596802293/ref=asap_bc?ie=UTF8))

------
eevilspock
Author fails to follow own advice:

    
    
      int printFirstNPositive(int maxToPrint, Collection<Integer> c)
    

The method name uses "N", but the param for N is named "maxToPrint". Confusing
and also violates his/her wasted space rule.

Instead:

    
    
      int printFirstNPositive(int n, Collection<Integer> c)
    

I think the short variable names "n" and "c" are fine since they are part of
the method signature and have unambiguous meaning, and also because the
implementation is so short (so no problem remembering that n and c are the
inputs.

------
RodericDay
In dynamic languages, like Python, I think it's often good to call variables
something like `fruit_list`, to quickly pick up on a bug where ie: `fruit_list
== {'apple'}`.

~~~
squeaky-clean
A convention I've always done for this is to just use a plural name. There are
fewer errors based on mixing up the names than you'd think, and it's very
readable.

    
    
        for fruit in fruits:
          assert fruit is not 'apple'
          print(fruit)
    
        assert 'banana' not in fruits
    

etc. Especially in Python, it makes code flow very much like English.

Edit: It also goes with the "don't put the type in the name" point, which I
agree with in most cases. Depending on your use case, it most likely won't
matter if fruits is a list, tuple, set, generator, whatever. The plural
implies an iterable interface. However, if the type does matter, I will often
use it in the name (in a dynamic lang like Python).

~~~
6502nerdface
I've always considered it a dangerous idiom in dynamic typed languages like
Python to create identifiers that differ from each other by only a single
character (fruit/fruits), point to completely different objects, and are used
in close proximity to each other. It's just asking for a hard-to-detect typo
that will blow up at runtime.

~~~
mixmastamyk
Hmm, don't think that actually happens very often, because it is so readable
this way.

~~~
lgunsch
I written python for the last 4 years, and I've never had typo problems of
that nature. I find the plural form to be so idiomatic it is expected and
easier to understand.

------
ederlf
I aggre with pretty much everything. However, some conventions only apply to
strongly-typed languages (e.g: Don't Put the Type in the Name)

------
newobj
Since when is English considered a romance language? I thought it was majority
Germanic in origin.

~~~
dragonwriter
English is a Germanic language with a strong Romance influence, thanks to the
Norman Conquest. (That is to say, you are quite correct that it is not a
Romance language.)

~~~
jakub_g
This pretty cool map shows distances between languages. English is Germanic
and French is Romance but they are quite close.

[https://elms.wordpress.com/2008/03/04/lexical-distance-
among...](https://elms.wordpress.com/2008/03/04/lexical-distance-among-
languages-of-europe/)

------
Aleman360
I love it when people use generic names and then add a two word comment
describing what it is.

I also love it when people use primitives for time spans along with the units
in the name or comment instead of TimeSpan/std::chrono.

~~~
jschwartzi
My favorite is when people use a good variable name and then put a two line
comment explaining what I could gather from the variable name.

------
maxxxxx
As a German I totally agree with teutonic naming. Who doesn't love words like
"Umsatzsteuervoranmeldung".

However, I disagree with the chapter "Remove Thoughtless One-Time Variables".
I much prefer having a variable I can check in the debugger than having the
result of some function passed into another function without being able to see
what the value is. Any halfways good optimizer will remove the varibale anyway
so there is no performance hit.

~~~
rootlocus
If the function doesn't have side effects (and even if it does), the IntelliJ
IDEA debugger will gladly evaluate the function call and show you its result
for java applications. PyCharm can also do this for python.

~~~
maxxxxx
The Visual Studio debugger can do that too but that works for only for
functions without side effects that can be executed repeatedly. This is often
not the case.

------
pklausler
Here's a tip along these lines: Use 'j' and 'k' for integral loop control
variables, not 'i'. Both 'j' and 'k' are pretty high-value Scrabble letters
and it's easier to search for their appearances in code. Apart from "break",
they don't appear in the reserved words of common programming languages.

(And never use 'l' as a variable name; but you knew that already.)

------
Camillo
> Most names should be Teutonic, following the spirit of languages like
> Norwegian, rather than the elliptical vagueness of Romance languages like
> English. Norwegian has more words like tannlege (literally "tooth doctor")
> and sykehus (literally "sick house"), and fewer words like dentist and
> hospital (which don't break down into other English words, and are thus
> confusing unless you already know their meaning).

Not only is this vaguely racist; it's also wrong, which is worse.

\- English is, in fact, a Germanic language.

\- Using more specific words (and English has _lots_ of words) is the
_opposite_ of vagueness. A "sick house" could be a house that contains sick
people, a house that is sick itself (rotten beams?), a noble family ("house")
whose fortunes have turned, etc. A "hospital" is, unambiguously, a facility
where the sick are given professional care. Of course, in a different timeline
"sickhouse" could have been the word for "hospital", but then it would have
been a word of its own, taking up the same amount of space in your mental
dictionary as "hospital" does.

\- Romance languages are, arguably, _less_ vague even in their grammar. You
know that thing where you just jam two words together and call it a day? You
see very little of that in Romance languages. Instead, you put a preposition
in there, which forces you to be more specific about the exact way in which
the two things are related.

\- Of course, a "Teutonic" fan would then say that this is a problem with
Romance language, and the ability to jam words together is what makes a
language truly rich. (Because it's easier to form new words? In which case,
see item 2.) And sure, it's ok to have preferences. But if you're going to be
a Grammar Nazi, or a literal Nazi, you better have a clue what you're talking
about.

~~~
rmk2
What he means, but phases poorly, is to use _compounds_.

On your other point, at least German is very specific with how compounds work
grammatically, namely that they follow a head-right principle which defines
genus and declination and which essentially relegates everything left of the
head to the status of further defining the head. Additionally, none of your
examples work in German for the term "Krankenhaus" (sick house/hospital) for
that very reason: a sick house (a house in disrepair) would have to be a
krankes Haus following general rules of declension, which would also be the
grammatically correct (though completely non-idiomatic) version for a fallen
noble house. And while there is a very specific way that defines how stems of
a compound are related, German can mark grammatical units differently from
English (and akin to Latin) by requiring the agreement of case/numerus/genus
between say an adjective and a noun, specifically making it grammatically
impossible for krankes Haus to be understood as hospital or Krankenhaus to be
understood as a dilapidated house.

edit: the above holds true for Norwegian and Danish as well, by the way.

------
kazinator
There is always this alternative: don't have any variables to name!

    
    
      (defun print-first-n-pos (n seq)
        [(opip (take n)
               (keep-if [orf zerop plusp])
               (progn
                 (mapdo (op put-string `@1 `) @1)
                 (put-line)
                 @1)
               (- n (length @1)))
         seq])
    
    
      $ txr -i first-n-pos.tl
      1> (print-first-n-pos 4 '(-1 2 3 4 5 6))
      2 3 4 
      1
      2> (print-first-n-pos 5 '(-1 -2 3 4 -5 6))
      3 4 
      3
    

Well, @1 is technically a variable. :)

------
jejones3141
Good advice about variable names (though surely "dentist" isn't all that
obscure), but the example function suffers from the boilerplate that the
author rightly says is a problem. Looking at the Java Collection interface,
the removeIf() description sounds like it actually modifies the Collection
rather than creating a new one. Is there a way in Java to do the equivalent of
the following Haskell (I'm being lazy and not writing a version for
Traversable)

    
    
        take n (filter (> 0) xs)

~~~
lmm
You can use the Java 8 streams interface, converting back and forth at the
ends. Or there's a method in Guava-collections (won't be lazy though). Or you
can use Scala.

------
awinter-py
I'm all for tricks that make 'coding in the small' easier, but grain of salt
on this -- reading a large codebase, esp one with external dependencies, is a
separate problem. In my day to day life (and not everybody is me, I know) the
large program reading problem is THE problem; comprehending functions is a
nice bonus but not as hard.

In small functions, I wish variable names were automatic based on type. If a
function has only one local of type T, it should automatically get name t or
something.

------
buckbova
My trouble with naming standards is the diversity of naming across
systems/languages.

For your standard crud app you could have a database record with field
ORD_NUM, service layer with property OrderNumber, and in javascript
orderNumber.

If all I do is live in one part of the stack this may not bother me. But when
I have to add a new field and propagate it through the stack I cringe at every
mapping.

Is it too late to camel case everything?

------
wyldfire
> iterating through a for loop using i is a well-established idiom that
> everyone instantly understands. Give that count was useless anyway, i is
> preferable since it saves 4 characters.

"Where does this idiom come from?" you might ask. Well, if I recall it's
mostly due to languages like Fortran which implicitly typed identifiers
starting with I through N as integers.

~~~
ChuckMcM
exactly right. Some jokes about writing fortran in any language focus on the
use of "I, J, and K" as indexes and counters. But in mathematics the common
iterator in a summation is also i, j, and k so mathematicians sometimes claim
ownership of the use of i as a count.

~~~
kps
Fortran, like most early programming languages, was explicitly modelled on
mathematical notation. There was debate whether allowing multi-letter variable
names was worth the loss of implicit multiplication. But today's programmer
can write COBOL in any language.

------
partycoder
I don't agree with this article. 1 character variables is not a good goal to
have.

For me, the second block is more readable than the "good" example. It has
issues, but it's more readable.

------
blastrat
Not trying to convince anybody of anything, but as a public service to expand
your mind, I strongly urge anyone interested in these types of ideas to FORGET
WHAT THEY THINK THEY KNOW OR HAVE HEARD and to REREAD Charles Simonyi's (he
invented WYSIWYG) seminal piece of his PhD thesis which now is some 40 years
old. Forget what you THINK you remember about these ideas--they've been
butchered in popular understanding--read the original work and digest his
system as a whole and on its own merits.

[EDIT add paragraph: Simonyi's overarching idea was to implement a novel
solution to a familiar problem which I'll try to state as succinctly as
possible: if two programmers are independently given the same programming
task, and they turn out to write down the exact same code, you have won.
Maintenance and working on other people's code is now solved if it's the same
code you would write yourself. That's the problem he is trying to solve while
also, incredibly, speeding up the process of independently writing code.]

[https://msdn.microsoft.com/en-
us/library/aa260976(v=vs.60).a...](https://msdn.microsoft.com/en-
us/library/aa260976\(v=vs.60\).aspx) (please read past dr. dimento's
introduction)

Pay particular attention to his notions of "type" that lead his naming system
quite logically to very opposite conclusions as OP. He's not talking about
underlying implementation types, he's talking about the properties of the
abtract types that you keep in your head and only attempt to capture in code.
Absolutely DO encode them in the name of the variable so it is completely
unambiguous what you mean, so it's a contract you will live up to; not for
communicating to the compiler, for communicating to other human beings: your
compiler talking to other human beings is not that effective.

As a simple example, how many times have you said to your coworker "you need
to pass me the file" to which they'll respond, "the file handle (by which they
mean POSIX), the file name, the file path, relative, absolute, socket, URI, or
do you mean the FILE pointer?" These are all notions of type that are best
resolved with a shorthand unambiguous (and yes, local) language which is
precise about type.

It helps you track meaningful distinctions and shed meaningless.

Bear in mind that this system comes from "the age of C"; as such, it helps
make simple concepts that many programmers find disturbingling confusing: if
"ch" means "it's a character", and p- as a prefix means "it's a pointer", then
a "ch" and a "* * ppch" will have the same type. What are the attributes of
that character type? You need to learn them or define them; I never said it
was a C char and you shouldn't think that either; it will be only if those are
the type attributes that are useful to your abstract type.

~~~
ldmoray
I was under the impression that Hungarian was largely not recommended. I find
it's redundant in strong static systems, and unhelpful in duck-typed systems.

~~~
blastrat
As I said, READ THE PIECE, forget about what you think you already know.

A discussion of what he actually said will be more interesting than a
discussion of what you misunderstand.

But in response to the point you raised, the purpose of Simonyi's system is
NOT to avoid compilation errors (what you call redundant). The naming
convention encapsulates precisely what programmers need to keep in their heads
while they code; humans are not compilers, and the type information involved
is NOT THE COMPILER OR LANGUAGE TYPE, it is the abstract (human) type.

It is to (1,2,3 might not be all or the only reasons) (1) speed the coding
task for the human (2) speed the maintenance task for the human and (3)
enhance programmer understanding of the code to eliminate errors of human
logic.

------
akkartik
Off-topic, but blogspot links are a constant frustration for me on the phone.
It's super easy for my fingers to swipe slightly left/right when scrolling and
triggering blogspot's next/previous post navigation. I can even accidentally
end up slightly scrolled horizontally and have no way to see the left side
again.

As a result I mostly ignore blogspot links. But this seems up my alley
([http://akkartik.name/post/readable-bad](http://akkartik.name/post/readable-
bad)). Anybody else run into these issues? Anybody have suggestions or
workarounds? Why _do_ technically savvy folks not notice how crappy blogspot
has gotten?

 _Edit_ : PSA for blogspot owners
[https://productforums.google.com/forum/m/#!topic/blogger/8hN...](https://productforums.google.com/forum/m/#!topic/blogger/8hNsCLpEn6U)

[http://chrisltd.com/blog/2012/03/blogger-mobile-
theme](http://chrisltd.com/blog/2012/03/blogger-mobile-theme)

~~~
gcr
Reader view on iOS makes blogspot, and lots of other articles, quite bearable.
(I assume it works?)

~~~
akkartik
Ah, why didn't I think of that?! Thanks!

 _Edit_ : Firefox on Android seems to eat much of the article in readable
mode, while Chrome or Opera on Android seem to have none. So I'm back at
square one..

------
andrewfromx
when it's coding as fast as humanly possible, the last thing I want to do is
slow down to think of good var names. I'll often just name something "foo" if
I can't think of a good name and come back and rename it later. Sometimes it's
a little better than foo but still not perfect but I'll leave that and move on
to something else. I really don't like the idea that code must be perfect.
Code is never perfect.

~~~
bovermyer
But what happens if you die and someone else has to pick up where you left
off?

~~~
Aldo_MX
someone else is going to cry because the coder is dead and the code is
unreadable

~~~
mcguire
Well, at least someone will be happy at the wake.

