Symptoms

---

What constitutes a poor name? The simple answer is that the name should explain exactly what is does or represents. However, this can lead to excessively long names that are cumbersome to read. The real answer is that the name must provide enough information so that its usage can be determined without much effort by the average programmer. Even this answer does not provide enough information for generating good names while programming. This answer serves only as a guideline by which to judge the names that are created. In the end, if the name serves its purpose well, it can be considered a success.

Comment Required?

One indicator that the name is not sufficient for its purposes is that a comment is required to explain what the variable is even when the context in which it is used is available. Of course, this criterion does not apply to names that are made public without their corresponding implementation details. These require commenting because there is no context available. However, you will find many cases where the function name is not sufficient even if the implementation is available for parsing.

Suppose you encountered a section of code that looked like this.

   if(itd()) {       // ...    }

What exactly does itd mean? Perhaps it could be made clearer by adding a comment:

   // If this object is initialized...    if(itd()) {       // ...    }

However, if you need the comment, what purpose does the name X serve? You end up with one set of text for the compiler to read and another for the programmer to read. This could easily get unsynchronized and cause numerous errors. It also makes the code harder to read. Instead, we could choose a better function name and let it communicate to both the compiler and the programmers:

   if(isInitialized()) {       // ...    }

This function name typically needs no explanation or comment for another programmer to understand that it is meant to check the initialization state of the object to which it belongs. A short comment might be required, however, for some automatic documentation systems. In this case, it is generally kept extremely short and to the point since it is not necessary except for external documentation.

Nevertheless, there can be cases where even a straightforward function name such as this might hide important information. Imagine that to be initialized, several functions must first be called other than just a function with the name initialize. This information will quite often be important to the caller of isInitialized. Since the name would become excessively long if these conditions were to be self-documenting, the use of a comment is called for here.

This leads us to the observation that when the comment is conveying information to the programmer that is already conveyed to the compiler in a less readable form, the names used are insufficient and therefore wasteful. Comments related to the implementation details should only be used to explain why and, when the algorithm is complex, sometimes how the code operates. The comments should not be necessary to explain what the code elements mean. Look for comments that are simply restating what the code does with different names, especially if the names used in the code sound ambiguous. This is a clear symptom of poorly chosen names.

Of course, if you don’t comment at all you will never discover any of this. Always read the code you have just written to determine if it is understandable. Pretend that you do not already know what it does and imagine what might be missing if you came at it from a fresh perspective. This is not easy, and even the best programmers will end up with code that is not fully understandable. An additional step that can help substantially is to have another programmer review the code to see if he understands what it does and why. Regular code reviews are a good means to provide this feedback without interrupting the normal workflow. Additionally, pair programming is another good way to obtain constant feedback from another programmer. This latter approach is an important part of the Extreme Programming methodology.

Dangers of Context

One danger to be particularly aware of because of its misleading nature is the context of the variable or code element. It is best to choose names that are still understandable despite small changes in the context. To better understand what we mean, we return to the name of this illness and its seminal example:

   for(int i = 2; i < 512; i *= i) {       bitMask &= i;    } 

Notice that i might be understandable within its current context because of the small scope of its existence. However, code does not stay fixed over time. For example, the loop contents might grow substantially over time, causing the initialization of i to be lost at the top and the meaning then requires a search. Another possibility is that i will be moved outside the loop:

   bitMask &= i;

Once again, the meaning might require a search to make clear what i does and how it should be used. In particular, it is not clear that i represents a bit-field with a single bit set. Actually, even in the first code snippet it is unclear what i is ultimately meant to represent, only that it is a power of two and therefore represents a bit-field with a single bit set. Therefore, although it might seem safe at the time, do not rely too heavily on context to provide the full meaning of a variable or code element.

Variables named according to their context can also end up with misleading names in anther context when the actual meaning of the variable changes. For example, you could be using an interpolation algorithm in one place to interpolate position, with the corresponding variable name position. If this same code snippet was then changed to interpolate color, but the variable name was not changed, it would be confusing to other programmers what the real intention was of the code. Instead, the variable should be renamed to color. Of course, if you are cut-and-pasting the code you should instead consider creating an interpolation function with a generic name such as value.

---