Clean code: Meaningful name (P.2)

See part 1 here

Do not use slang

If the names are too specific, they will often be remembered with the person who feels happy and only those people remember those stories. Do we know what the function named HolyHandGrenade supports? Certainly this function is a specific name but perhaps in this case it is better to name DeleteItems.

The smart choice is still more than entertainment values. Too specific naming in code snippets often occurs in intimate or slang cases. For example, do not use the name whack () to explain meaning kill (). Do not use local names when talking like eatMyShort () to interpret abort (). Say what you think means. The meaning here is what you say.

Choose a word for each concept

Choose a word for each abstract concept and add it. For example, equivalent complex methods of different classes have fetch, retrieve and get names. How can you remember the method's name in each class? Sadly, you often have to remember which company, group or individual wrote the library or class to know which name to use, or it will take considerable time to search.

Modern IDEs such as Eclipse and IntelliJ provide what can be used in that context, such as a list of methods that can be called on an object. But note that this list does not often give us the comments you wrote around the method name and parameter list. You are really lucky if the IDE tells you the name of the parameter of the real method. Method names must be independent and consistent so you can choose the right method without looking for anything else.

Similarly, having controller, manager and driver in the same source will be confusing.

What is the fundamental difference between DeviceManager and Protocol-Controller? Why don't both of them have controller or manager names? Both have really Driver? The name makes you think that these two objects are of two very different types as well as two different classes.

A consistent term has great benefits for those who use your source code.

No pun

Avoid using a word for two purposes. Using a term for two different ideas is basically a word game.

If you adhere to the rule "one from one concept", then you make multiple classes have, for example, an add method. It doesn't matter how much the return value or input parameter is, but the add methods have the same meaning.

However, you should consider using add words for "consistent" reasons when you really don't add in the same meaning. Suppose that we have the add method in multiple classes, which is to create a new value by adding or connecting two values ​​with cassava. Now we write a new class that has a method to give a parameter to a set. Should we call it add? It seems to be consistent because we already have many methods named add, but in this case the meaning is different, so it is better to use the name insert or append. If you call this new method add, it is a word game.

Our purpose, as authors, is to make the source code as easy to understand as possible. We want our source code to be able to surf quickly, not a heavy study. We want to use the popular paper cover template where the author is responsible for clarifying rather than the academic model where the work of the school is deepening meaning.

Use the name of the solution domain

Remember that your code readers are programmers. So use the terminology of computer science, names in algorithms, design names, math names, etc. It wouldn't be very nice if all names are of the business domain because we don't want our colleagues I have to run and ask the customer what each name means when they know the concept by another name.

The accountVisitor name is very meaningful to the developer who knows the VISITOR design pattern. What do programmers who don't know JobQueue mean? There are many technical things that programmers must know. Choosing the technical names for these things is often the most logical.

Use business domain name

When you are working on non-programmer ("programmer-eese") things, use the business name. At least your code maintenance programmer can ask the professional expert about its meaning.

Separating business concepts and solutions is part of being a good developer and designer. Code that needs to care about business concepts should bring the name of the business.

Add meaningful context

There are very few names that are meaningful in themselves, mostly not. You need to name the context, by putting them in the class, function, package that has a clear name to help readers understand. When you do not do these things, you can use the prefix as the final solution.

Imagine you have variables with the following names: 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 state variable mean if you see it alone in a method? Do you understand right away that it's part of an address?

You can add context using good money: addrFirstName, addrLastName, adddrState, etc. 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. At that time, even the compiler knew that these variables belonged to a larger structure.

See the method in the code 2-1. Do these variables need more meaningful context? The name of the method provides only part of the context; The algorithm provides the rest. Once you finish reading the method, you see three variables, verb and pluralModifier are the part of the "guess statistics" message. Unfortunately, we have to guess the context. The first time you look at the method, the meaning of these variables is unclear.

Code 2-1: Turning in an unclear context.

The method is a bit long and the variable is used from beginning to end. To divide the function into smaller ones, we need to create the GuessStatisticsMessage class and let these three variables become properties of this class. This creates a clear context for all three variables. They are clearly part of GuessStatisticsMessage. This context improvement also allows for more explicit algorithms by breaking down into smaller functions (See code 2-2).

Code 2-2: Variable context.

Do not add unfounded contexts

In the imaginary application called "Gas Station Deluxe", adding a GSD prefix to the class names is a bad idea. Honestly, you're working against your own tool. When you type G and press the key to complete, you get a very long list of classes in the system. Is that a wise job? Why is it difficult for IDE to help you?

Similarly, when you create the MailingAddress class in the accounting module of GDS, you name the class GSDAccountAddress. Then you need a mail address for the customer directory application. Do you use GSDAccountAddress? Is that the right name? Ten of the 17 characters are redundant and have no meaning.

Short names are usually better than long names, if they are clear. It is necessary to not add context.

accountAddress and customerAddress are good names for Address class instances, but they are bad class names. Address is good class name. If I need to distinguish between a MAC address, a gateway address and a Web address, I should consider PostalAddress, MAC and URI. These names are more accurate.

Last words

The naming is difficult because it requires good description skills and a shared culture. It is teaching rather than technical, business or management. As a result, many people in this field do not learn to do very well.

People are often afraid of changing names because they worry that some other developers will evaluate. We do not encourage this fear and in fact we are indebted to changing names (in a better way). We use modern tools to solve the details so that we can focus on whether the code is the same as the paragraph and the sentence is not, or at least the same as the table and data structure (Not the time Any one sentence is also the best way to display data). Maybe you surprised someone by changing your name, like other source code improvements. Don't let it get in your way.

Follow these rules and see if you can improve your source code easier to read. If you maintain someone else's source code, use the re-structuring tool to help solve these problems. It will pay off capital in a short time and continue to give interest in the long term.

ITZone via magazine programming