20 Chapter 2: Meaningful Names

Beware of using names which vary in small ways. How long does it take to spot the
subtle difference between a XYZControllerForEfficientHandlingOfStrings in one module
and, somewhere a little more distant, XYZControllerForEfficientStorageOfStrings? The
words have frightfully similar shapes.
Spelling similar concepts similarly is information. Using inconsistent spellings is dis-
information. With modern Java environments we enjoy automatic code completion. We
write a few characters of a name and press some hotkey combination (if that) and are
rewarded with a list of possible completions for that name. It is very helpful if names for
very similar things sort together alphabetically and if the differences are very obvious,
because the developer is likely to pick an object by name without seeing your copious
comments or even the list of methods supplied by that class.
A truly awful example of disinformative names would be the use of lower-case L or
uppercase O as variable names, especially in combination. The problem, of course, is that
they look almost entirely like the constants one and zero, respectively.
int a = l;
if ( O == l )
a = O1;
else
l = 01;
The reader may think this a contrivance, but we have examined code where such
things were abundant. In one case the author of the code suggested using a different font
so that the differences were more obvious, a solution that would have to be passed down to
all future developers as oral tradition or in a written document. The problem is conquered
with finality and without creating new work products by a simple renaming.

Make Meaningful
Distinctions
Programmers create problems for them-
selves when they write code solely to sat-
isfy a compiler or interpreter. For example,
because you can’t use the same name to refer
to two different things in the same scope,
you might be tempted to change one name
in an arbitrary way. Sometimes this is done by misspelling one, leading to the surprising
situation where correcting spelling errors leads to an inability to compile.2
It is not sufficient to add number series or noise words, even though the compiler is
satisfied. If names must be different, then they should also mean something different.

2. Consider, for example, the truly hideous practice of creating a variable named klass just because the name class was used
for something else.
Use Pronounceable Names 21

Number-series naming (a1, a2, .. aN) is the opposite of intentional naming. Such
names are not disinformative—they are noninformative; they provide no clue to the
author’s intention. Consider:
public static void copyChars(char a1[], char a2[]) {
for (int i = 0; i < a1.length; i++) {
a2[i] = a1[i];
}
}
This function reads much better when source and destination are used for the argument
names.
Noise words are another meaningless distinction. Imagine that you have a Product
class. If you have another called ProductInfo or ProductData, you have made the names dif-
ferent without making them mean anything different. Info and Data are indistinct noise
words like a, an, and the.
Note that there is nothing wrong with using prefix conventions like a and the so long
as they make a meaningful distinction. For example you might use a for all local variables
and the for all function arguments.3 The problem comes in when you decide to call a vari-
able theZork because you already have another variable named zork.
Noise words are redundant. The word variable should never appear in a variable
name. The word table should never appear in a table name. How is NameString better than
Name? Would a Name ever be a floating point number? If so, it breaks an earlier rule about
disinformation. Imagine finding one class named Customer and another named
CustomerObject. What should you understand as the distinction? Which one will represent
the best path to a customer’s payment history?
There is an application we know of where this is illustrated. we’ve changed the names
to protect the guilty, but here’s the exact form of the error:
getActiveAccount();
getActiveAccounts();
getActiveAccountInfo();
How are the programmers in this project supposed to know which of these functions to call?
In the absence of specific conventions, the variable moneyAmount is indistinguishable
from money, customerInfo is indistinguishable from customer, accountData is indistinguish-
able from account, and theMessage is indistinguishable from message. Distinguish names in
such a way that the reader knows what the differences offer.

Use Pronounceable Names

Humans are good at words. A significant part of our brains is dedicated to the concept of
words. And words are, by definition, pronounceable. It would be a shame not to take

3. Uncle Bob used to do this in C++ but has given up the practice because modern IDEs make it unnecessary.
22 Chapter 2: Meaningful Names

advantage of that huge portion of our brains that has evolved to deal with spoken lan-
guage. So make your names pronounceable.
If you can’t pronounce it, you can’t discuss it without sounding like an idiot. “Well,
over here on the bee cee arr three cee enn tee we have a pee ess zee kyew int, see?” This
matters because programming is a social activity.
A company I know has genymdhms (generation date, year, month, day, hour, minute,
and second) so they walked around saying “gen why emm dee aich emm ess”. I have an
annoying habit of pronouncing everything as written, so I started saying “gen-yah-mudda-
hims.” It later was being called this by a host of designers and analysts, and we still
sounded silly. But we were in on the joke, so it was fun. Fun or not, we were tolerating
poor naming. New developers had to have the variables explained to them, and then they
spoke about it in silly made-up words instead of using proper English terms. Compare
class DtaRcrd102 {
private Date genymdhms;
private Date modymdhms;
private final String pszqint = "102";
/* ... */
};
to
class Customer {
private Date generationTimestamp;
private Date modificationTimestamp;;
private final String recordId = "102";
/* ... */
};
Intelligent conversation is now possible: “Hey, Mikey, take a look at this record! The gen-
eration timestamp is set to tomorrow’s date! How can that be?”

Use Searchable Names

Single-letter names and numeric constants have a particular problem in that they are not
easy to locate across a body of text.
One might easily grep for MAX_CLASSES_PER_STUDENT, but the number 7 could be more
troublesome. Searches may turn up the digit as part of file names, other constant defini-
tions, and in various expressions where the value is used with different intent. It is even
worse when a constant is a long number and someone might have transposed digits,
thereby creating a bug while simultaneously evading the programmer’s search.
Likewise, the name e is a poor choice for any variable for which a programmer might
need to search. It is the most common letter in the English language and likely to show up
in every passage of text in every program. In this regard, longer names trump shorter
names, and any searchable name trumps a constant in code.
My personal preference is that single-letter names can ONLY be used as local vari-
ables inside short methods. The length of a name should correspond to the size of its scope