Series Clean Code - Meaningful Names

Continue the Clean Code series, today I'll talk about Meaningful Names topic. As you know, names are everywhere in software. We named the variables, functions, list of parameters, classes, packages. After that, we also named the file and folder included it. We named, named and named. Because we need to do it many times, so we need to do it well.

And there are some basic rules to create a good name.

• Use Intention-Revealing Names
• Avoid Disinformation
• Use Pronounceable Names
• Use Searchable Names
• Avoid Encodings
• Avoid Mental Mapping
• Class Names
• Method Names
• Don’t Be Cute
• Don’t Pun
• Use Solution Domain Names
• Use Problem Domain Names
• Add Meaningful Context
• Don’t Add Gratuitous Context

Use Intention-Revealing Names

• Use the name to expose the purpose. 
• Choosing good names takes time, but saves a lot when used.
• So pay attention to the names you named and change them when you find a better name. 
• When you do that, everyone who reads your code (including you) will find it easier to understand.
• The name of the variable, function, class should answer all the big questions. 
• It will tell you why it exists, what it does, and how it is used. 
• If a name needs to be explained, this name is not mean to be descriptive.

Avoid Disinformation

• Avoid false information.
• Avoid putting false suggestions that overshadow the real meaning of the code, as the acronym may be misunderstood. For example, you should name a account group accountGroup, bunchOfAccount, accounts instead of accountList.
• Be careful when using names not much different. For example: XYZControllerForEfficientHandlingOfStrings and XYZControllerForEfficientStorageOfStrings
• Variables with similar spelling are also problematic when used.

Make Meaningful Distinctions

• Make the distinction clear. 
• Should not use "Number-Series" (a1, a2, ..., aN), as it conflicts with naming purposes, because the name does not provide information, does not provide the intent of the writer.

• Use source and destination names
• "Noise word" is also a meaningless individuality. For example: You have the Product class, if you have another class called ProductInfo or ProductData >> You set different names without making any difference, Info and Data are two noise words.
• Using articles like "a", "an" or "the" does not make a difference. For example, what is the difference between the three variables: dog, aDog, and theDog? 

Use Pronounceable Names 

• Use a pronounced name. 
• If you can not pronounce the names, you can not discuss them without thinking.

Use Searchable Names

• Use searchable name. 
• Variable names and constant names have a problem that is not easy to determine their position. 
• If variables and constants are used in multiple places in the code, then the name should be more friendly.

Avoid Encodings

• Avoid using encryption.
• The current encoding is sufficient so there is no need to add it.
• Adding strange encryption to a simple name raises the bar for decoding.
• It is unreasonable to ask a new employee to read the strange coding added while the available coding is enough. 
• Hungarian Notation: https://en.wikipedia.org/wiki/Hungarian_notation
• Member Prefixes:

• Interfaces and Implementations

- Sometimes special circumstances require coding. For example, building an AbstractFactory, Factory is created as an interface and executed by a specific class. 
- How can this interface be named? IShapeFactory or ShapeFactory?

Avoid Mental Mapping

• Avoid mental mapping.
• Count variables of the loop can be named i, j, k (never l) if its scope is small and no name conflicts with it, because this "single-letter" name is for traditional loop.
• However, in most other cases it is a poor choice, which causes the reader to map the spirit to a real concept.
• Professional programmers use their ability to write code that makes other people understand. 

Class Names

• Class and object names should be nouns or noun phrases such as Customer, Account, WikiPage, etc.
• Class names avoid words like Manager, Processor, Data, Info, ...
• Class names also avoid verbs. 

Method Names

• The name of the method should be a verb or verb phrase like postPayment, deletePage, save, ...
• Methods of accessors, mutators, predicates should be named with their values and prefixes such as get, set, is 

• When the constructors overload, use the static factory method with names and arguments. 

Don't Be Cute

• Do not use slang and local words. For example, do not use the whack () name to interpret it as kill (). Do not use local names when talking as eatMyShorts () to interpret abort ().
• Say what you mean, mean what you say.

Don't Pun

• Do not play words.
• Do not use a word for two purposes. For example, the add method does not care about the added position. However, when we are interested in adding placements, using the name of the insert or append will be more appropriate.

Use Solution Domain Names

• Use the name of the solution domain.
• Remember that people who read your code are programmers. So use the terms of computer science, the name in the algorithm, the name in design form, math name, ...
• It would not be nice if all of the names are of the business domain because we do not want our colleagues to run and ask customers the meaning of each name when they know the concept by another name.

Use Problem Domain Names

• Use the name of the business domain. 
• When you are working with non-programmers ("programmer-eese"), use the business name. 
• At least your code maintenance programmer can ask professional experts about its meaning.

Add Meaningful Context

• Add context makes sense.
• There are few names that are meaningful in themselves, most are not.
• You need to name the context, by putting them in a class, function, namespace, and so on.
• When you can not do this, you can use the prefix as the last solution.
• For instance, imagine you have variables with names like: firstName, lastName, street, houseNumber, city, state, and zipcode.
• Placing them side by side is very clear that it will form an address.
• But what does the state variable mean if you see it alone?
• Do you understand that it is part of an address?
• You can add context using good money: addrFirstName, addrLastName, adddrState, ...
• At least readers will understand that these variables are part of a larger structure.
• Of course, the better solution is to create a class called Address.

Don’t Add Gratuitous Context

• Do not add unfounded contexts. 
• Short names are clearly better than long names. For example, suppose we have a "Gas Station Deluxe", adding the GSD prefix to the class names is a bad idea. 
• When you create the MailingAddress class in the GDS Account module, you name the class GSDAccountAddress. Is that a correct name? 10 of 17 characters are superfluous and have no meaning. 

See you in next chapter about Functions in Clean Code...