Cure

---

As with many of the other illnesses, numerous examples of code that exhibits this illness exist. Some of this code you are likely to want to use or be required to use. As you use this code, you can refactor the names used to improve the readability. This will not only help other programmers on your team, but also help you when you need to change or fix the code later in development.

Read the Code

As you incorporate code into your project that is not hidden away in a library, read the code to come to a better understanding of what the code is doing. As you read the code, you might discover that certain names do not read naturally. These names slow the parsing of your code and are the ones that require refactoring.

Once encountered, you must first be sure that you understand what is occurring in the code. If you are sure you know what is happening, then proceed to replace all instances of the variable or code element with a new name. Refactoring and code examination tools can help ensure that all instances and only the correct instances are replaced (Figure 7.2). Once the new name is in place, reread the code to determine if the readability has increased. If not, choose a new name and repeat this procedure.

Figure 7.2: Refactoring a member function name using IntelliJ’s IDEA to make it more readable. IDEA ensures that all instances are properly renamed.

Comments to Code

The naming process can be assisted if the code has been commented because of the poor name choices that were used. If you encounter comments that are explaining what is happening, then you should attempt to incorporate these comments into the code itself. This process helps accomplish several improvements to the resulting code. The code is easier to read, both because the naming has improved and the comments are no longer in the way. Further, the comments represented a duplication of information that required extra maintenance.

To give a better idea of this process, suppose the drawKeyFrame code from earlier in this chapter started out looking like this:

   /**     * Draw key frame function designed to  * illustrate readable code naming.     */    public void drawKeyFrame() {       // If the configuration is initialized and has       // a value for interpolation...       if(configuration.itd() && configuration.get(INTERP) != NONE) { // If the configuration value for // interpolation is linear, draw this // object at the value calculated using // linear interpolation. // Otherwise, the value should be spline // and so we draw this at the value // calculated using spline interpolation.          if(configuration.get(INTERP) == LIN) {             draw(lin());          } else {             draw(spl());          }       }    }

First, we remove the need for commenting the initialization check:

      // If the configuration has       // a value for interpolation...       if(configuration.isInitialized() && configuration.get(INTERP) != NONE) {

Then we add a new function to the configuration so that we can just check if the value exists without having to get it, which is also more readable with a new name:

      if(configuration.isInitialized() && configuration.has(INTERPOLATION)) {

Now we change the equality into a function call and give the retrieval function a better name:

         if(configuration.getValueOf( INTERPOLATION).is(LINEAR)) { // Draw this // object at the value calculated using // linear interpolation.             draw(lin());          } else { // Otherwise, the value should be // spline and so we draw this at // the value calculated using // spline interpolation.             draw(spl());          } 

Next, we make the spline check more explicit, both for readability and to avoid problems if other types are added to the configuration file:

         if(configuration.getValueOf( INTERPOLATION).is(LINEAR)) { // Draw this // object at the value calculated using // linear interpolation.             draw(lin());          } else if(configuration.getValueOf( INTERPOLATION).is(SPLINE)) { // Draw this at // the value calculated using // spline interpolation.             draw(spl());          }

We then change the name of the draw function to indicate what is being drawn:

         if(configuration.getValueOf( INTERPOLATION).is(LINEAR)) { // Value calculated using // linear interpolation.             drawThisAt(lin());          } else if(configuration.getValueOf( INTERPOLATION).is(SPLINE)) { // Value calculated using // spline interpolation.             drawThisAt(spl());          }

The interpolation functions also need better names to indicate what they are doing:

         if(configuration.getValueOf( INTERPOLATION).is(LINEAR)) {             drawThisAt( resultOfLinearCalculation());          } else if(configuration.getValueOf( INTERPOLATION).is(SPLINE)) {             drawThisAt( resultOfSplineCalculation());          } 

Finally, we put it all together to get a more readable function:

   /**     * Draw key frame function designed to  * illustrate readable code naming.     */    public void drawKeyFrame() {       if(configuration.isInitialized() && configuration.has(INTERPOLATION)) {          if(configuration.getValueOf( INTERPOLATION).is(LINEAR)) {             drawThisAt( resultOfLinearCalculation());          } else if(configuration.getValueOf( INTERPOLATION).is(SPLINE)) {             drawThisAt( resultOfSplineCalculation());          }       }    }

---