Naming - Learning notes of Clean code (2)

Naming

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

2. 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.
   • Beware of using names which vary in small ways.

3. Make meaningful distinctions

   • Number-series naming (a1, a2, … aN) is the opposite of intentional naming. They provide no clue to the author’s intention.
   • 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 different without making them mean anything different.

4. Use pronounceable names

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.

6. Avoid encodings

7. Member prefix

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

8. Avoid mental mapping

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

9. Class names

   • Classes and objects should have noun or noun phrase names like Customer, WikiPage, Account, and AddressParser.
   • A class name should not be a verb.

10. Method names

    • Methods should have verb or verb phrase names like postPayment, deletePage, or save.
    • When constructors are overloaded, use static factory methods with names that describe the arguments. For example,

    Complex fulcrumPoint = Complex.FromRealNumber(23.0);
    

11. Don’t be cute.

    • Say what you mean. Mean what you say.

12. 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.
    • If you follow the “one word per concept” rule, you could end up with many classes that have, for example, an add method. As long as the parameter lists and return values of the various add methods are semantically equivalent, all is well.

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

14. Use problem domain names

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

15. Add meaningful context

    • There are a few names which are meaningful in and of themselves—most are not. Instead, you need to place names in context for your reader by enclosing them in well-named classes, functions, or namespaces.

16. Don’t add gratuitous context

    • In an imaginary application called “Gas Station Deluxe,” it is a bad idea to prefix every class with GSD.

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). Most of the time we don’t really memorize the names of classes and methods. We use the modern tools to deal with details like that so we can focus on whether the code reads like paragraphs and sentences, or at least like tables and data structure (a sentence isn’t always the best way to display data). You will probably end up surprising someone when you rename, just like you might with any other code improvement. Don’t let it stop you in your tracks. It will pay off in the short term and continue to pay in the long run.