Index

Day 1 - Meaningful names

Use intention-revealing names

• Choosing good names takes time but saves more than it takes
• The name of a variable, function, or class, should answer all the big questions
• If a name requires a comment, then the name does not reveal its intent
• Often, the problem is not the simplicity of the code but the implicity of the code

Avoid misinformation

• We should avoid words whose entrenched meanings vary from our intended meaning
• Do not refer to a grouping of accounts as accountList unless it’s actually a List. The word List means something specific to programmers. So accountGroup or accounts would be better.

Make meaningful distinction

• Programmers create problems for themselves when they write code solely to satisfy a compiler or interpreter. For example, 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 numbers, series or noise words, even though the compiler is satisfied. If names must be different, then they should also mean something different
• Consider:
  

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

  This function reads much better when source and destination are used for the argument names

Use pronounceable names

• Humans are good at words, and words are, by definition, pronounceable
• If you can’t pronounce it, you can’t discuss it without sounding like an idiot

Use searchable names

• The length of a name should correspond to the size of its scope
• If a variable or constant might be seen or used in multiple places in a body of code, it is imperative to give it a search-friendly name

Avoid encodings

• We have enough encodings to deal with without adding more to our burden. Encoding type or scope information into names simply adds an extra burden of deciphering
• Hungarian Notation (deprecated - to be avoided)
• You also don’t need to prefix member variables with m_ anymore. You should be using an editing environment that highlights or colorizes members (objects attributes) to make them distinct

Avoid mental mapping

• Readers shouldn’t have to mentally translate your names into other names they already know
• This is a problem with single-letter variable names. Certainly a loop counter may be named i or j if its scope is very small and no other names can conflict with it. This is because those single-letters name for loop counter are traditionals

Class names

• Classes and objects should have noun or noun phrase names

Methods names

• Methods should have verb or verb phrase names

Don’t be cute

• Choose clarity over entertainment value (humor lasts)
• Don’t use the name whack() to mean kill(). Don’t tell little culture-dependent jokes like eatMyShorts() to mean abort()
• Say what you mean, mean what you say

Pick one word per concept

• 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

Don’t pun

• Avoid using the same word for two purposes. Using the same term for two different ideas is essentially a pun

Use solution domain names

• Remember that the people who read your code will be programmers. The name AccountVisitor means a great deal to a programmer who is familiar with the Visitor pattern

Add meaningful context

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

Don’t add gratuitous context

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