11.7. Kinds of Names to Avoid

Here are some guidelines regarding variable names to avoid:

Avoid misleading names or abbreviations Make sure that a name is unambiguous. For example, FALSE is usually the opposite of TRUE and would be a bad abbreviation for "Fig and Almond Season."

Avoid names with similar meanings If you can switch the names of two variables without hurting the program, you need to rename both variables. For example, input and inputValue, recordNum and numRecords, and fileNumber and fileIndex are so semantically similar that if you use them in the same piece of code you'll easily confuse them and install some subtle, hard-to-find errors.

Avoid variables with different meanings but similar names If you have two variables with similar names and different meanings, try to rename one of them or change your abbreviations. Avoid names like clientRecs and clientReps. They're only one letter different from each other, and the letter is hard to notice. Have at least two-letter differences between names, or put the differences at the beginning or at the end. clientRecords and clientReports are better than the original names.

Cross-Reference

The technical term for differences like this between similar variable names is "psychological distance." For details, see "How "Psychological Distance" Can Help" in Section 23.4.

Avoid names that sound similar, such as wrap and rap Homonyms get in the way when you try to discuss your code with others. One of my pet peeves about Extreme Programming (Beck 2000) is its overly clever use of the terms Goal Donor and Gold Owner, which are virtually indistinguishable when spoken. You end up having conversations like this:

I was just speaking with the Goal Donor  Did you say "Gold Owner" or "Goal Donor"? I said "Goal Donor." What? GOAL - - - DONOR! OK, Goal Donor. You don't have to yell, Goll' Darn it. Did you say "Gold Donut?"

Remember that the telephone test applies to similar sounding names just as it does to oddly abbreviated names.

Avoid numerals in names If the numerals in a name are really significant, use an array instead of separate variables. If an array is inappropriate, numerals are even more inappropriate. For example, avoid file1 and file2, or total1 and total2. You can almost always think of a better way to differentiate between two variables than by tacking a 1 or a 2 onto the end of the name. I can't say never use numerals. Some real-world entities (such as Route 66 or Interstate 405) have numerals embedded in them. But consider whether there are better alternatives before you create a name that includes numerals.

Avoid misspelled words in names It's hard enough to remember how words are supposed to be spelled. To require people to remember "correct" misspellings is simply too much to ask. For example, misspelling highlight as hilite to save three characters makes it devilishly difficult for a reader to remember how highlight was misspelled. Was it highlite? hilite? hilight? hilit? jai-a-lai-t? Who knows?

Avoid words that are commonly misspelled in English Absense, acummulate, acsend, calender, concieve, defferred, definate, independance, occassionally, prefered, reciept, superseed, and many others are common misspellings in English. Most English handbooks contain a list of commonly misspelled words. Avoid using such words in your variable names.

Don't differentiate variable names solely by capitalization If you're programming in a case-sensitive language such as C++, you may be tempted to use frd for fired, FRD for final review duty, and Frd for full revenue disbursal. Avoid this practice. Although the names are unique, the association of each with a particular meaning is arbitrary and confusing. Frd could just as easily be associated with final review duty and FRD with full revenue disbursal, and no logical rule will help you or anyone else to remember which is which.

Avoid multiple natural languages In multinational projects, enforce use of a single natural language for all code, including class names, variable names, and so on. Reading another programmer's code can be a challenge; reading another programmer's code in Southeast Martian is impossible.

A more subtle problem occurs in variations of English. If a project is conducted in multiple English-speaking countries, standardize on one version of English so that you're not constantly wondering whether the code should say "color" or "colour," "check" or "cheque," and so on.

Avoid the names of standard types, variables, and routines All programming-language guides contain lists of the language's reserved and predefined names. Read the list occasionally to make sure you're not stepping on the toes of the language you're using. For example, the following code fragment is legal in PL/I, but you would be a certifiable idiot to use it:

if if = then then    then = else; else else = if;

Don't use names that are totally unrelated to what the variables represent Sprinkling names such as margaret and pookie throughout your program virtually guarantees that no one else will be able to understand it. Avoid your boyfriend's name, wife's name, favorite beer's name, or other clever (aka silly) names for variables, unless the program is really about your boyfriend, wife, or favorite beer. Even then, you would be wise to recognize that each of these might change, and that therefore the generic names boyfriend, wife, and favoriteBeer are superior!

Avoid names containing hard-to-read characters Be aware that some characters look so similar that it's hard to tell them apart. If the only difference between two names is one of these characters, you might have a hard time telling the names apart. For example, try to circle the name that doesn't belong in each of the following sets:

eyeChartl      eyeChartI      eyeChartl TTLCONFUSION   TTLCONFUSION   TTLC0NFUSION hard2Read      hardZRead      hard2Read GRANDTOTAL     GRANDTOTAL     6RANDTOTAL ttl5           ttlS           ttlS

Pairs that are hard to distinguish include (1 and l), (1 and I), (. and ,), (0 and O), (2 and Z), (; and :), (S and 5), and (G and 6).

Do details like these really matter? Indeed! Gerald Weinberg reports that in the 1970s, a comma was used in a Fortran FORMAT statement where a period should have been used. The result was that scientists miscalculated a spacecraft's trajectory and lost a space probe to the tune of $1.6 billion (Weinberg 1983).

Cross-Reference

For considerations in using data, see the checklist on page 257 in Chapter 10, "General Issues in Using Variables."

cc2e.com/1191

Checklist: Naming Variables

General Naming Considerations

• Does the name fully and accurately describe what the variable represents?

• Does the name refer to the real-world problem rather than to the programming-language solution?

• Is the name long enough that you don't have to puzzle it out?

• Are computed-value qualifiers, if any, at the end of the name?

• Does the name use Count or Index instead of Num?

Naming Specific Kinds of Data

• Are loop index names meaningful (something other than i, j, or k if the loop is more than one or two lines long or is nested)?

• Have all "temporary" variables been renamed to something more meaningful?

• Are boolean variables named so that their meanings when they're true are clear?

• Do enumerated-type names include a prefix or suffix that indicates the category for example, Color_ for Color_Red, Color_Green, Color_Blue, and so on?

• Are named constants named for the abstract entities they represent rather than the numbers they refer to?

Naming Conventions

• Does the convention distinguish among local, class, and global data?

• Does the convention distinguish among type names, named constants, enumerated types, and variables?

• Does the convention identify input-only parameters to routines in languages that don't enforce them?

• Is the convention as compatible as possible with standard conventions for the language?

• Are names formatted for readability?

Short Names

• Does the code use long names (unless it's necessary to use short ones)?

• Does the code avoid abbreviations that save only one character?

• Are all words abbreviated consistently?

• Are the names pronounceable?

• Are names that could be misread or mispronounced avoided?

• Are short names documented in translation tables?

Common Naming Problems: Have You Avoided…

• …names that are misleading?

• …names with similar meanings?

• …names that are different by only one or two characters?

• …names that sound similar?

• …names that use numerals?

• …names intentionally misspelled to make them shorter?

• …names that are commonly misspelled in English?

• …names that conflict with standard library routine names or with predefined variable names?

• …totally arbitrary names?

• …hard-to-read characters?