Use Intention Revealing Names

It should tell

• why it exists

• what it does

• how it is used

If a name requires a comment, then the name does not reveal its intent.

Replace

int d;

with

int numberOfDays;

Avoid Disinformation

• Avoid leaving false clues that obscure the meaning of code

• Example: variable hp is a poor one as it can mean hp laptop, hp (hypotenuse) and so on

• Try to avoid naming data type in a variable name (debatable)

  • Example: accounts in place of accountList should be used.

• Long names which vary in just small parts can also be difficult

  • XYZControllerForHandlingStrings vs XYZControllerForHandlingListOfStrings

Make Meaningful Distinctions

• Naming things like account1, account2 is not meaningful

• Distinguish names in such a way that the reader knows what the differences offer.

Use Pronounceable Names

Use Searchable Names

• Single-letter names and numerics are not easily locatable in a body of text

• Longer names are better than shorter names (in general)

• Searchable names are better than a simple constant value (e.g NUMBER_OF_DAYS over 30)

• Single letter names can ONLY be used inside short methods as a local variable (Debatable: There as well use relevant names)

The length of a name should correspond to the size of its scope

Avoid Encoding

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

Hungarian Notation

• It is not needed in modern languages

  • Example avoid

    • PhoneNumber phoneString
      // name not changed when type changed

Member Prefixes

• Earlier developers used to name member variables like

  • m_variableName

  • Used variableName instead

Interfaces and Implementations

Do not encode Interfaces

• Leave interfaces unadorned (simple) unlike (IShapeFactory -> Interface, ShapeFactory -> Concrete Class)

• Rather encode the implementation like ShapeFactoryImpl or CShapeFactory

Avoid Mental Mapping

• Readers shouldn't have to mentally translate your variable names to other names

  • Example: Single letter names

Class Names

• Class and Objects should be noun

• Example: Customer, Product

• The book says verbs should be avoided like: Manager, Processor, Info
  (Debatable : In the real world they are inevitable)

Method Names

• Should have verb and non verb phrases
  Example: postMessage

• Accessors, mutators and predicates should be named for their value prefixed with get, set and is

• When constructors are overloaded, use static factory methods with names that describe their arguments
  Example : Complex number = Complex.fromRealNumber(2.0) over
  Complex number = new Complex(2.0)

  Enforce such static methods by making corresponding constructors private

Don't be Cute

• Choose clarity over entertainment value

Say what you mean. Mean what you say.

Pick one word per concept

• Pick one word for one abstract concept
  For example, do NOT use GET, FETCH and RETRIEVE as equivalent methods of different classes.
  The same goes for the manager, driver, controller

Don't Pun

• Avoid using the same name for two purposes
  Example: one might use the method add for consistency only even if they are being used in different senses which is wrong.
  Usage 1: Add being used to create and concatenate values and create a new result
  Usage 2: Put a single value into the collection

Use solution domain names

• Since programmers will be the readers of the code, one should freely use CS terms, algorithm names etc.

Use problem domain names

• When there is no "programmer-ease", use the name from the problem domain

• Code that has more to do with problem-domain concepts should have names drawn from the problem domain.

Add meaningful context

• Few names are meaningful by themselves

• Rest require context using classes, functions or namespaces

• The last resort to add context is using the prefix

Don't add gratuitous context

• For an application named "Gas Station Deluxe" don't add "GSD" as a prefix to all the classes.

• Shorter names are better than longer ones, so long as they are clear.

• Add no more context to the name than necessary.

---

This wraps up chapter 2 of Clean Code.

See you in the next one.