Beware of ambiguous names

Key Points
"What else can this name mean ?" Actively check every name by constantly asking yourself this question.

As a matter of fact, this creative, constantly trying "wrong understanding" method can effectively discover and correct ambiguous names. As shown in the example in this article, we will explore misunderstandings of the names we see at any time by means of "watching the album with a donkey-walking and watching", and then select a better name.

Example: Filter ()
Suppose you have written a piece of code to operate the database result set:

Results = Database. all_objects.filter ("year <= 2011 ")
So what data does results contain?

All objects that meet year <= 2011
All objects that do not meet year <= 2011
 

The problem arises from the ambiguous word "filter", which does not clearly indicate whether it means "select" or "Remove ". Therefore, you should avoid using filter, which is too easy to misunderstand!
If you want to "select", a better name is select. If you want to "Remove", a better name is exclude.

Name a Boolean Value
When naming a Boolean variable or a function returns a Boolean value, pay special attention to the true and false meanings. Here is a very dangerous example:

Bool read_password = true;
The meaning of this Code depends on how it was read at the time (there is no other meaning). Obviously, there are two completely different understandings:

Read Password required
The password has been read.
In this case, do not use the word read. You can use need_password or user_is_authenticated instead.

In general, adding words "is", "has", "can", and "shoshould" makes the meaning of Boolean values clearer and easier to understand.
For example, there is a function called SpaceLeft (). At first glance, we will think that the value returned by this function is a number. If you need to explicitly return a Boolean value, a better name is HasSpaceLeft ().
Also, try not to use the negative short sentences for naming. For example:

Bool disable_ssl = false;
The following code is easier to understand and better suited to the original intention:

Bool use_ssl = true;

Meets user expectations
Many names are misleading, because a user has an expected definition for a name, but the meaning of the Code may not. In this case, it is best to make a "concession" and change the name to eliminate misleading information.

Example: get *()
Many programmers use this encoding specification: A method starts with get to express a "lightweight accesser" to return internal members. Violation of this specification can easily mislead users. Avoid the java code snippet in the following example:

Public class StatisticsCollector {
Public void addSample (double x ){...}
 
Public double getMean (){
// Iterate through all samples and return total/num_samples
}
...
}
Here, the implementation of getMean is to enumerate all the data in the past and calculate its average value. If the data volume is large, the overhead of this step will be very large. However, a programmer who does not know the situation will call it very carelessly and assume it is a very cheap call.
Therefore, this method should be renamed to something similar to computeMean (), which seems to be a costly operation (or, another option is to rewrite its implementation, becomes a real lightweight operation ).

Example: list: size ()
Here is a naming question for the C ++ standard library. The result of this Code is that it is difficult to locate and fix problems similar to those that cause fast running of server turtles:

Void ShrinkList (list <Node> & list, int max_size ){
While (list. size ()> max_size ){
FreeNode (list. back ());
List. pop_back ();
}
}
This bug causes the author to be unaware of the list. size () is an O (n) complex operation-it counts the total number of nodes in the linked list one by one instead of returning the total number of computed nodes, which leads to ShrintList being an O (n2).
Technically speaking, this code is okay and can pass all unit tests. However, when ShrintList () is called and a list containing hundreds of millions of records is passed in, it may take several hours.
You may think that this is the caller's incorrect use. He/she has not carefully read the relevant documents! This is indeed the case. However, in fact, the list. size () operation here is not a constant-time operation, which is too surprising! All other C ++ container classes are the size () method of the constant time.
If we name size () as countSize () or countElements (), similar errors will be greatly reduced. The implementer of the C ++ standard library may think of using a size () method to match other containers, such as vector and map, so that API consistency looks better. It is precisely because of this that programmers are easy to mistakenly use and think that this is a very fast operation, just like other containers! Fortunately, the latest C ++ standard requires that size () is O (1) complexity.

 

From the grape city control technical team blog