2 Meaningful Names

Introduction

Names are everywhere in software. We name our variables, our functions, our arguments, classes, and packages. We name our source files and the directories that contain them. Because we do so much of it, we’d better do it well.

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.

Avoid disinformation

Programmers must avoid leaving false clues that obscure the meaning of code. We should avoid words whose entrenched meanings vary from our intended meaning.
Do not refer to a grouping of accounts as an accountList. If the container is not actually a List, it may lead to false conclusions. Even if the container is a List, it’s probably better not to encode the container type into the name. Just plain accounts would be better.
Beware of using names which vary in small ways. Spelling similar concepts similarly is information. Using inconsistent spellings is disinformation. A truly awful example of disinformative names would be the use of lower-case L or upper-case O as variable names, especially in combination.

Make meaningful distinctions

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. 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. ‘Info’ and ‘Data’ are indistinct noise words like ‘a’, ‘an’, and ’the’. The variable ‘customerInfo’ is indistinguishable from ‘customer’, and ’theMessage’ is indistinguishable from ‘message’.

Use pronounceable names

If you can’t pronounce it, you can’t discuss it without sounding like an idiot. This matters because programming is a social activity.

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. Single-letter names can ONLY be used as local variables inside short methods. The length of a name should correspond to the size of its scope.

Avoid encodings

Encoding type or scope information into names simply adds an extra burden of deciphering. Encoded names are seldom pronounceable and are easy to mis-type. Hungarian Notation and other forms of type encoding are simply impediments. You also don’t need to prefix member variables with ‘m_’ anymore. Your classes and functions should be small enough that you don’t need them. If I must encode either the interface or the implementation, I choose the implementation. Calling it ‘ShapeFactoryImp’ is preferable to encoding the interface (IShapeFactory). I don’t want my users knowing that I’m handing them an interface.

Avoid mental mappings

Readers shouldn’t have to mentally translate your names into other names they already know. This problem generally arises from a choice to use neither problem domain terms nor solution domain terms.

Class names

Classes and objects should have noun or noun phrase names.

Method names

Methods should have verb or verb phrase names. Accessors, mutators, and predicates should be named for their value and prefixed with get, set, and is according to the javabean standard. When constructors are overloaded, use static factory methods with names that describe the arguments. For example:

Complex fulcrumPoint = Complex.FromRealNumber(23.0);

Don’t be cute

If names are too clever, they will be memorable only to people who share the author’s sense of humor. Say what you mean. Mean what you say.

Pick one word per concept

Pick one word for one abstract concept and stick with it. For instance, it’s confusing to have fetch, retrieve, and get as equivalent methods of different classes. Likewise, it’s confusing to have a controller and a manager and a driver in the same code base.
A consistent lexicon is a great boon to the programmers who must use your code.

Don’t pun

Avoid using the same word for two purposes. Let’s say we have many classes where add will create a new value by adding or concatenating two existing values. Now let’s say we are writing a new class that has a method that puts its single parameter into a collection. Should we call this method add? As the semantics are different, we should use a name like insert or append. To call the new method add would be a pun.

Use solution domain names

Remember that the people who read your code will be programmers. So go ahead and use computer science (CS) terms, algorithm names, pattern names, math terms, and so forth. There are lots of very technical things that programmers have to do. Choosing technical names for those things is usually the most appropriate course.

Use problem domain names

When there is no “programmer-eese” for what you’re doing, use the name from the problem domain. At least the programmer who maintains your code can ask a domain expert what it means.

Add meaningful context

You need to place names in context for your reader by enclosing them in well-named classes, functions, or namespaces. In a function that is a bit long, it might be possible to make some variables of the function fields of a new class to provide a clear context for that variables.

Don’t add gratuitous context

Shorter names are generally better than longer ones, so long as they are clear. Add no more context to a name than is necessary. The names accountAddress and customerAddress are fine names for instances of the class Address but could be poor names for classes.

Final words

The hardest thing about choosing good names is that it requires good descriptive skills and a shared cultural background. This is a teaching issue rather than a technical, business, or management issue. As a result many people in this field don’t learn to do it very well.
People are also afraid of renaming things for fear that some other developers will object. We do not share that fear and find that we are actually grateful when names change (for the better).

Previous: 1 Clean Code

Up: Contents

Next: 3 Functions