Ten Tips Gives your code a Meaningful Names — Clean Code Part 2

As mention in the previous part of the clean code, we discuss the problems of the speed coding and the desire to finish the product and bringing it to the market as fast as possible.

one of the most common issues that programmers make is Bad Naming.

chose appropriate names is part of everywhere in software. We name variables, functions, arguments, classes, packages, source files.

Because this task is repeated over and over, we need to find a better way to do it well, rather than naming randomly and make a mess, just by following some rules.

Choosing good names takes time but saves more than it takes.

In the few coming points, we will discuss every point in detail.

1. Use intention-revealing names.

The name of a variable, function, or class, should answer all these 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 t; // time in days

The name t refers to nothing. We should choose a name that specifies what is being measured and the unit of that measurement:

int timeInDays;
int timeInMinutes;

Choosing names that reveal intent can make it much easier to understand and change code.

Notice that the performance of the running code doesn’t change and still the same. But the code has become much more explicit.

With these simple name changes, it’s not difficult to understand what’s going on. This is the power of choosing good names.

2. Avoid disinformation.

Programmers must avoid words whose entrenched meanings vary from our intended meaning.

For example, hp aix and sco would be poor variable names because they are the names of Unix platforms or variants.

Even if you are coding a hypotenuse and hp looks like a good abbreviation, it could be disinformative.

Do not refer to the products group as productsList unless it’s actually a List because the word List means something specific to programmers. If the container holding the accounts is not actually a List, it may lead to false conclusions, so maybe just products would be better.

Don’t use names that have a little difference between them.

For example

ControllerForEfficientHandlingOfStrings //in class and ControllerForEfficientStorageOfStrings //in another class.

Because the words have almost had the same shapes.

3. Make meaningful distinctions.

every name has to haveing a clear different meaning. Because you can’t use the same name to refer to two different things in the same scope, you might change one name. Sometimes this is done by misspelling one, for example, creating a variable named klass just because the name class was used for something else.

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

for example

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.

adding meaningless words product class. If you have another called productInfo or productData, you have made the names different without making them mean anything different.

Redundant words must not be used.

• word variable should never appear in a variable name.
• word table should never appear in a table name.
• variable type shouldn’t be attached to a variable name, Name is better than NameString because name won’t be anything else but text.

4. Use pronounceable names.

make your names pronounceable.

If you can’t pronounce it, you can’t discuss it without sounding like an idiot.

we good at remembering what we can say, so if you using unpronounceable words as names for variable or class or function or whatever anything, you lose this benefit of using pronounceable names, This matters because programming is a social activity.

For example:

convert this

class DtaRcrd102 {
 private Date genymdhms;
 private Date modymdhms;
 private final String pszqint = ”102”;
 };

to

class Customer {
 private Date generationTimestamp;
 private Date modificationTimestamp;;
 private final String recordId = ”102”;
 };

5. Use searchable names.

Single-letter names and numeric constants have a problem in that they are not easy to locate across a large file code.

If you have a fixed number of products lets say 4125 and while writing the code you use this number in many places, if another developer work on this code after you and he needs to change this constant, he can’t search easily and find it, how he can guess a particular number like this 4125? so to solve this issue if you defined a constant with the name PRODUCTS_COUNT, it will be helpful for three reasons:

• if this number needs to be changed it will be changing in one place only.
• you can search for it.
• the shape of all capitals laters makes it easy for your eyes and other developers to find this constant in vary large file code.

using a single letter as a variable name is a bad choice, imagine you name a variable e, and then you search for it to check or change something as a letter like e is the most frequency letter used in English you will almost git many search results you don’t need it, so to avoiding this don’t use a single letter for any variable name especially if this variable on a global scope.

6. Avoid Mental Mapping.

Mental Mapping is a kind of relation build between two names, Let’s take a common example, in for loop we usually use i instead of index as a variable name it’s fine if the scope of for loop is small, but if the scope is large or having a nested loop or maybe loop over a list with thee or four variables — as in some programming language which called destruction-, is not the best practice if we have I, j, k variables for product, seller, category respectively, you maybe don’t have any issue with that because you are the one who builds this list structure and knows how it looks like, but for other developers, they need to trace your code and see the structure of this list to figure out what is I,j, and k.

And it not just in loops but this common example to illustrate the idea of what we talking about, and maybe happened anywhere on your code, in short words Don’t force other developers to tie real name with names you created, so the more you do that, the bigger the map that the developers need to made it in their minds to work with your code.

7. Class names and Method Names.

Classes and objects 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.

Methods should have verb or verb phrase names like postPayment, deletePage, or save. Accessors, and predicates should be named for their value and prefixed with get, set.

string name = employee.getName();
 customer.setName(”Name”);

When constructors are overloaded, use static factory methods with names that describe the arguments. For example:

constructor overloaded: is in some cases you may have more than one constructor for a class and evey constructor take differnt prammters and for every case you make a diffrent action, in this case the instance you create from class is bassed on wich pramters you pass.

Example:

public class Demo{

Demo(){

…

}

Demo(int id){

…

}

Demo(string name){

…

}

}

so:

Complex fulcrumPoint = Complex.FromRealNumber(23.0);

is better than

Complex fulcrumPoint = new Complex(23.0);

Consider enforcing their use by making the corresponding constructors private.

8. Pick one word per concept.

Pick one word for one abstract concept and stick with it. For instance, it’s confusing to have fetch, retrieve, and get as equivalent methods of different classes.

Likewise, it’s confusing to have a controller and a manager in the same code base. What is the essential difference between a DeviceManager and a Protocol-Controller? Why are both not controllers or both not managers? The name leads you to expect two objects that have very different type as well as having different classes.

A consistent lexicon is a great boon to the programmers who must use your code.

unlike the concept of Pick One Word, there is another concept called Don’t Pun which encourages you to avoid using the same word for two purposes.

punning is using the same term for two different ideas.

9. solution domain vs problem domain names.

solution domain names:

Remember that the people who read your code will be programmers. So go ahead and use computer science (CS) terms, algorithm names, pattern names, math terms, and so forth. It is not wise to draw every name from the problem domain because we don’t want our coworkers to have to run back and forth to the customer asking what every name means when they already know the concept by a different name.

The name AccountVisitor means a great deal to a programmer who is familiar with the VISITOR pattern. What programmer would not know what a JobQueue was? There are lots of very technical things that programmers have to do. Choosing technical names for those things is usually the most appropriate course.

problem domain names:

When there is no “programming term” 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.

Separating solution and problem domain concepts is part of the job of a good programmer and designer. The code that has more to do with problem domain concepts should have names drawn from the problem domain.

10. Add meaningful context.

Let's say you have data for a user (name, email, address, ..etc), it will be helpful if you grab them all together under class called User, so then you use user.name, user.email, user.address, the difference between the two approaches that in the first one if you use address only in someplace the reader maybe don’t git that this address belongs to the user. In other words, you add a meaningful part to the variable name to be clear what is this variable is using for.

In contrast to adding meaningful context, there is

• adding gratuitous context:

In an imaginary application called “Gas Station Deluxe,” it is a bad idea to prefix every class with GSD, you are working against your tools. You type G and press the completion key and are rewarded with a mile-long list of every class in the system. Why make it hard for the IDE to help you?

• Member Prefixes:

Don’t use any prefixes for variables like m_ or anything like that.

bad example:

public class Part {
 private String m_dsc; // The textual description
 void setName(String name) {
 m_dsc = name;
 }
 }

need to be converted to

public class Part {
 String description;
 void setDescription(String description) {
 this.description = description;
 }
 }

Developers ignore the prefix to see the meaningful part of the name. The more we read the code, the less we see the prefixes.