Chapter 2 - Meaningful Names

Use Intention-Revealing Names

The name of a variable, function, or class should answer all the big questions.
It should tell you why it exists, what it does, and how it is used.
If a name requires a comment, then the name does not reveal its intent.
A bad naming example:

int d; // elapsed time in days

A good naming example:

int elapsedTimeInDays;
int daysSinceCreation;
int daysSinceModification;
int fileAgeInDays;

Making programs and code blocks explicit is important. Be clear with what you name things.
People should be able to look at your code and understand what it does without having to read the comments.

Avoid Disinformation

Avoid words whose entrenched meanings vary from our intended meaning. For example hp may seem like a good abbreviation for hypotenuse, but it is also a common abbreviation for hit points in games.
Another example is using accountList for a group of accounts, this would be okay if it was in fact a List but if it is a Collection or Set then it would be disinformation.
It's important to be wary of the appearance of your variables as well. For example using lower case "L" and upper case "O" in variable names can be confusing as they look like 1 and 0.

Make Meaningful Distinctions

• Distinguish names in such a way that the reader knows what the differences offer. If names must be different, then they should also mean something different.
  Adding some numbers on the end of a variable to distinguish variables to satisfy the compiler is not a good practice.
  Below is a bad example because the names a1 and a2 are not very descriptive:

public static void copyChars(char a1[], char a2[]) {
    for (int i = 0; i < a1.length; i++) {
        a2[i] = a1[i];
    }
}

NOTE: There is nothing wrong with using prefixes like a and the aslong as they make meaningful distinctions.
For example, a might be for local variables and the might be for function arguments, aValue and theValue are then meaningful distinctions.
Naming a variable theZork just because you already have a zork is not a meaningful distinction.

Noise Words are redundant words that don't add any meaning. Like putting the word variable in a variable name or function in a function name.

Use Pronounceable Names

If you can't pronounce it, you can't discuss it without sounding like an idiot.
Programming is a social activity and the language you use should be pronounceable.

Use Searchable Names

Single letter names and number variables can be hard to search for with grep. Any searchable name trumps a constant in code. A valid exception to the rule is that single-letter names can ONLY be used as a local variable inside a short method.
This is still not ideal as it could be unclear what it is being used for.

for (int i = 0; i < 34; i++) {
    s += (t[i] * 4) / 5;
}

int realDaysPerIdealDay = 4;
const int WORK_DAYS_PER_WEEK = 5;
int sum = 0;
for (int j = 0; j < NUMBER_OF_TASKS; j++) {
    int realTaskDays = taskEstimate[j] * realDaysPerIdealDay;
    int realTaskWeeks = (realdays / WORK_DAYS_PER_WEEK);
    sum += realTaskWeeks;
}

Looking at the two samples above, you can see now that you can search for WORK_DAYS_PER_WEEK & realDaysPerIdealDay much easier than you can search for 5 & 4, mainly due to the potential of there being multiple 5s and 4s throughout the code.

Avoid Encodings

We have enough encodings to deal with and adding more has no beneficial effect.
It simply makes things harder to read and understand.
Nowadays we have IDEs that can tell us what type a variable is, so there is no need to encode the type into the name.
Hungarian notation and other forms of encoding these days are nothing more than empediments to reading and understanding code.

Member Prefixes

It is not necessary to prefix member variables with m_ or m to distinguish them from local variables anymore.
This was a common practice in the past when IDEs were not as advanced as they are now.

Interfaces and Implementations

There is no need to prefix interfaces with I or C for classes.

Avoid Mental Mapping

Readers shouldn't have to mentally translate your names into other names they already know.
Clarity is king.

Class Names

Class names should be nouns or noun phrases, not verbs. For example, Customer, WikiPage, Account, and AddressParser are all good examples of class names.
Bad examples include, Manager, Processor, Data, and Info.

Method Names

Method names should be verbs or verb phrases.
For example, postPayment, deletePage, save, get, and set are all good examples of method names.

Don't Be Cute

Choose clarity over entertainment value.
Don't use puns or jokes in your names. Like eatMyShorts() which actually means abort().

Pick One Word per Concept

Pick one word for one abstract concept and stick with it.
For example, it's confusing to have fetch, retrieve, and get as equivalent methods of different classes.
Being consistent is important.

Don't Pun

Avoid using the same word for two purposes.
Using the same word for two different purposes is essentially a pun.
For example, add can mean either append something to a collection or perform addition.

Use Solution Domain Names

Use technical terms that programmers would understand.
Where possible stay away from naming things after the problem domain.
This can be confusing to programmers who are not familiar with the problem domain.
Avoiding this can ultimately avoid asking the customer for details and saving time.

Use Problem Domain Names

When there is no "programmer-eese" for what you're doing, use the name from the problem domain. For example, if you're working on a payroll system, use names like Employee, Payroll, Salary, and Tax.
The code will be more readable to those who are familiar with the problem domain.

Add Meaningful Context

In long methods or classes, it's okay to use longer names to add context.
For example, state might be okay for a local variable in a short method, but in a longer method, it might be better to use addressState or customerState.
Context can be added via prefixes and even suffixes.

Don't Add Gratuitous Context

Shorter names are generally better than longer ones, as long as they are clear. For example, accountAddress is not as good as address in a class called Account.

Final Words

• The name of a variable, function, or class should answer all the big questions.
• It should tell you why it exists, what it does, and how it is used.
• If a name requires a comment, then the name does not reveal its intent.
• Be clear with what you name things.
• People should be able to look at your code and understand what it does without having to read the comments.
• Clarity is king.
• Pick one word for one abstract concept and stick with it.
• Use technical terms that programmers would understand.

Return