We name so much, we’d better name well

No comments

Names are everywhere in software (variables, functions, arguments, classes, source files etc…). Because we name so much, we’d better name well.
So choose your names thoughtfully 😉
Here come rules for creating good names (introduced by @UncleBobMartin).

Communicate your intent

The name of a variable, function, class or any other piece of code, should answer all the big questions:

  • why it exists
  • what it does
  • how it is used

If a name requires a comment, then the name does not reveal its intent.
Bad:
int d; // elapsed time in days
Good:
int elapsedTimeInDays;

Why? Choosing names that reveal intent can make it much easier to understand and change the code.
The code gets more explicit and you can tell what’s going on without digging in too deep.

Avoid Disinformation

Leaving false clues that obscure the meaning of the code. So avoid words whose established meanings vary from our intended meaning.
For example, git, grep, wc would be poor variable names because they are the names from the Unix/git world.

Or don’t refer to a grouping of accounts as an accountList unless it’s actually a List.

Also… Don’t try to satisfy a compiler. It’s smart enough.

Number-series naming (a1, a2, .. aN) is the opposite of intentional naming. Such names are not disinformative – they are noninformative. They provide no clue to the author’s intention.

For example:
public static void copyChars(char a1[], char a2[])
Reads much better when source and destination are used for the argument names.
public static void copyChars(char source[], char destination[])

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. Info and Data are indistinct noise words like a, an, and the.

Noise words are redundant.

How is NameString better than Name? Would a Name ever be a floating point number? If so, it breaks an earlier rule about disinformation.
Or IRestResponse merchantAccountResponse may be as well IRestResponse merchantAccount.

In the absence of specific conventions, the variable moneyAmount is like money, customerInfo like customer, accountData like account, and theMessage like message. Determine names in such a way that the reader knows the difference.

Pronounceable names

Humans are good at words. A significant part of our brains is dedicated to the concept of words. And words are, by definition, pronounceable. It would be a shame not to take advantage of that huge portion of our brains that have evolved to deal with spoken language. So make your names pronounceable.

If you can’t pronounce it, you can’t discuss it without sounding like an idiot. “Well, over here on the bee cee arr three cee enn tee we have a pee ess zee kyew int, see?” This matters because programming is a social activity.” (Uncle Bob)

And isn’t generationTimestamp nicer than genymdhms?

Avoid encodings

Objects are strongly typed, and editing environments have advanced such that they detect a type error long before you can run a compile! Even in weakly typed languages like JavaScript your suite of unit tests and proper naming will be your best defense.

Choose parts of speech well

Classes, objects, and variables should have noun or noun phrase names like Customer, WikiPage, Account, and AddressParser. Avoid words like Manager, Processor, Data, or Info in the name of a class. A class name should not be a verb. So use TextReader instead of ReadText.

Methods/functions should have verb or verb phrase names like PostPayment, DeletePage, or Save.

Bool variables and methods that return them should be predicates. For example: isPaymentProcessed, hasVendorMerchantAccounts. They also read better in an if statement if(is PaymentProcessed)

Choose technical names for technical things that programmers have to do (the name MalsResponseBuilder means a great deal to a programmer familiar with the Builder pattern).

When there is no “programmer-ease” 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.

Pick one word per concept. It’s confusing to have fetch, retrieve, and get as equivalent methods of different classes.
Likewise, it’s confusing to use PaymentProcessor and PaymentService to describe the same system.

Also, using the same word for different purposes is misleading.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

w

Connecting to %s