Notes Of Clean Code — Chapter 2 (Meaningful Names)

Previous Chapter : Clean Code

Names are everywhere in software. We name our variables, methods, classes, jar files, war files, source files..

We should choose names our variables, methods or classes that reveal their intentions. When someone(or you) read these, they must understand that why it exist, what it does, how it used.

https://thecodinglove.com/content/028/searching_meaningful_variable_name2.png

Look at the code below;
The name d reveals nothing. And If we add comment to variable, It means names doesn’t reveal its intent.

int d; // elapsed time in days

If we give these kind of names, It’s easier to understand their intention. And we don’t need to add any comments.

int elapsedTimeInDays;
int daysSinceCreation;
int daysSinceModification;
int fileAgeInDays;

The word “List” means something specific to programmers. Avoid using a List unless It’s a list.

Beware of using similar names in nearby modules. If you give a XYZControllerForEfficientHandlingOfStrings in one module and, give a XYZControllerForEfficientStorageOfStrings in neaby, It takes a time to find different.

Another example of poor names is using lowercase “l(L)” or uppercase “O(o)”. Because they look like one and zero.

int a = l;
if ( O == l )
 a = O1;
else
 l = 01;

We can’t use the same name in the same scope while writing code. And we change a name by adding a number or making a typo.

The names like a1, a2, .. aN are meaningless. They provide no clue.

public static void copyChars(char a1[], char a2[]) {
  for (int i = 0; i < a1.length; i++) {
    a2[i] = a1[i]; 
   }
}

We should use pronouncable names. When you discuss your code, If you pronounce the variable like that “gen why emm dee aich emm ess”, It has a problem in your variable name.

class DtaRcrd102 {
  private Date genymdhms; 
  private Date modymdhms;
  private final String pszqint = "102";
  /* ... */
};

Try this one:

class Customer {
  private Date generationTimestamp; 
  private Date modificationTimestamp;;
  private final String recordId = "102";
  /* ... */
};

While you name, careful that they shouldn’t be single-letter names or numeric constant. Use MAX_CLASSES_PER_STUDENT instead of 7.

The name “e”, It’s most common letter in the English language. It’s show up in every of text in every program.

Compare:

for (int j=0; j<34; j++) {
  s += (t[j]*4)/5;
}

  int realDaysPerIdealDay = 4;
        const int WORK_DAYS_PER_WEEK = 5;
        int sum = 0;
        for (int j = 0; j < NUMBER_OF_TASKS; j++) {
            int realTaskDays = taskEstimate[j] * realDaysPerIdealDay;
            int realTaskWeeks = (realdays / WORK_DAYS_PER_WEEK);
            sum += realTaskWeeks;
        }

Sum is not useful name but at least is searchable. And trying to find 5 is easier now.

Let’s say building an ABSTRACT FACTORY for the creation of shape. Use simple name like a ShapeFactory. Because when use IShapeFactory, it’s distracting and giving too much information to the user. If for implemantation class use ShapeFactoryImp.

When you name classes and objects, use noun or noun phrase. Like Address, Customer, Phone, WikiPage.. A class name shouldn’t be a verb.

Methods should have verb or verb phrase names. Like getPayments, deletePage, save..
Accessors(getters), mutators(setters) and predicates(return true/false) should be named for their value and prefixed with get, set and is.

string name = employee.getName();
customer.setName("mike");
if (paycheck.isPosted())...

Avoid using similar meaning words for different purpose or different meaning words for same purpose.

It’s confusing to have a controller, a manager and a driver. What is the difference between a DeviceManager and a Protocol Controller? Choose one and use it.

Let’s say we have a add method that adding or concatenating two existing value. And we are writing a new class that puts its single parameter into a collection. We shouldn’t call this method add. Because add has a different semantic in our code base. We should use a name like insert or append.

When you see firstName, lastName, street, houseNumber, city, state and zipCode variables together, you know they are form an address. But what if you saw state variable alone, how do you know exactly that means address ?

It’s understandable, when you add context by using prefixes like addrFirstName, addrState.. A better solution is to create a class named Address.

Look at the code in the example below:

private void printGuessStatistics(char candidate, int count) {
 String number;
 String verb;
 String pluralModifier;
 if (count == 0) {
   number = "no";
   verb = "are";
   pluralModifier = "s";
 } else if (count == 1) {
   number = "1";
   verb = "is";
   pluralModifier = "";
 } else {
   number = Integer.toString(count);
   verb = "are";
   pluralModifier = "s";
 }
 String guessMessage = String.format(
   "There %s %s %s%s", verb, number, candidate, pluralModifier
 );
 print(guessMessage);
}

The function is a bit too long. We can split the function into smaller pieces. We need to create a GuessStatisticsMessage class and put three variables.

public class GuessStatisticsMessage {
 private String number;
 private String verb;
 private String pluralModifier;
 public String make(char candidate, int count) {
   createPluralDependentMessageParts(count);
   return String.format(
     "There %s %s %s%s", 
     verb, number, candidate, pluralModifier );
 }

 private void createPluralDependentMessageParts(int count) {
   if (count == 0) {
   thereAreNoLetters();
   } else if (count == 1) {
     thereIsOneLetter();
   } else {
     thereAreManyLetters(count);
   }
 }

 private void thereAreManyLetters(int count) {
   number = Integer.toString(count);
   verb = "are";
   pluralModifier = "s";
 }

 private void thereIsOneLetter() {
   number = "1";
   verb = "is";
   pluralModifier = "";
 }

 private void thereAreNoLetters() {
   number = "no";
   verb = "are";
   pluralModifier = "s";
 }
}

Next Chapter : Functions