<<Clean Code>> Quotes: 2. Meaningful Names

1. Using Intention-Revealing Names

The name of a variable, function, or class, should answer all the big quetions. 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.

2. Avoid Disinformation

Programmers must avoid leaving false clues that obscure the meaning of code. We should avoid words whose entrenches meanings vary from our intended meaning.

e.g. hp, aix, and sco would be poor variable names.

Spelling similar concepts similarly is information. Using inconsistent spellings is disinformation.

3. Make Meaningful Distinctions

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.

Make meaningful Distinctions

Number-series naming {a1,a2,...aN} is the opposite of intentional naming. Such names are not disinformative—they are non informative; they provide no clue to the author’s intention.

Noise words are another meaningless distinction. Noise words are redundant. E.g. While having class Product, also have another called ProductInfo or ProductData.

Distinguish names in such away that the reader knows what the differences offer.

4. Use Pronounceable Names

E.g. genymdhms should be GenerationTimestamp.

5. 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.

My personal preference is that 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.

6. Avoid Encodings

Encoding type or scope information into names simply adds an extra burden of deciphering.

1. Hungarian Notation

It’s only for the old time when the compiler did not check types.

2. Member Prefixes

You don’t need to prefix member variable with m_ any more.

3. Interfaces and Implementations

E.g. IShapeFactory and ShapeFactory

7. Avoid Mental Mapping

This is a problem with single-letter variable names.

One difference between a smart programmer and a professional programmer is that the professional understands that clarity is king.

8. Class Names

Classes and objects should have noun or noun phrase names. Avoid words like Manager, Processor, Data, or Info in the name of a class.

9. Method Names

Methods should have verb or verb phrase names like postPayment, deletePage, or save. 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.

E.g. Complex fulcrumPoint = Complex.FromRealNumber(23.0); is better than Complex fuldrumPoint = new Complex(23.0);

Consider enforcing their use by making the corresponding constructors private.

10. Don’t Be Cute

Say what you mean, Mean what you say.

E.g. whack() and kill(), eatMyShorts() and abort().

11. Pick One Word per Concept

Pick one word for one abstract concept and stick with it. It’s confusing to have fetch, retrieve, and get as equivalent methods of different classes.

It’s confusing to have a controller and a manager and a driver in the same code base. What are the difference between them?

A consistent lexicon is a great boon to the programmers who must use your code.

12. Don’t Pun

Avoid using the same word for two purposes.

Our goal, as authors, is to make our code as easy as possible to understand

13. Use Solution Domain Names

Remember that the people who read your code will be programmers, So go ahead and use CS terms, algorithm names, pattern names, math terms, and so forth.

14. Use Problem Domain Names

Separating solution and problem domain concepts is part of the job of a good programmer and designer.

15. Add Meaningful Context

You need to place names in context for your reader by enclosing them in well-named classes, functions, or namespaces. When all else fails, then prefixing the name maybe necessary as a last resort.

16. 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.