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.
int d; // elapsed time in days
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.
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.
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.
“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?
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.