[CleanCode] Meaningful Names [Part 1]

In this series of posts , I would try to share with you some of my highlights on Clean Code Chapters.
Names are everywhere in software. We name our variables, our functions, our arguments,
classes, and packages.Because we do so much of it, we’d better do it well. What follows are some simple rules for creating
good names.

In this post my focus would be on Chapter 2.

1- User Intention-Revealing Names

  • Names should reveal intents and we are serious about that.

  • Your chosen name should answers the three main questions

    why it exists, what it does, and how it is used
    

Good Names doesn't require comments to explain them

Check the following code sample and try to deduce what is its purpose ?

public List<int[]> getThem() {
List<int[]> list1 = new ArrayList<int[]>();
for (int[] x : theList)
if (x[0] == 4)
list1.add(x);
return list1;
}

Was it difficult to understand the purpose of the code ? What does the constant 4 refer to ? What does list1 represent ?

Now , check it again after doing some renamings.

public List<int[]> getFlaggedCells() {
List<int[]> flaggedCells = new ArrayList<int[]>();
for (int[] cell : gameBoard)
if (cell[STATUS_VALUE] == FLAGGED)
flaggedCells.add(cell);
return flaggedCells;
}

What about it now ?

public List<Cell> getFlaggedCells() {
List<Cell> flaggedCells = new ArrayList<Cell>();
for (Cell cell : gameBoard)
if (cell.isFlagged())
flaggedCells.add(cell);
return flaggedCells;
}

Choosing good names takes time but saves more than it takes.
So take care with your names and change them when you find better ones.

2- Avoid Disinformation

  • We should avoid words whose meanings vary from our intended meaning. For example, if we have a group of accounts , we shouldn't call
    them accountList unless they are really represented with a list. If the container holding the accounts is not actually a List, it may lead to false conclusions.1 So accountGroup or
    bunchOfAccounts or just plain accounts would be better.

  • Beware of using names which vary in small ways. How long does it take to spot the difference between invoicedOpenOrders and invoicedOpenOrder or between PDFEfficientStringsController and PDFEfficientListsController

  • A truly awful example of disinformative names would be the use of lower-case L or
    uppercase O as variable names, especially in combination. The problem, of course, is that they look almost entirely like the constants one and zero

3- Make Meaningful Distionctions

Sometimes developers need to have two things with the same name and to satisfy the compiler they may add a noise word or a random number to the second name. In fact this may make the code compile but it is obviously a wrong attitude.

If names must be different, then they should also mean something different.

  • Number-series naming (a1, a2, .. aN) is the opposite of intentional naming. They are disinformative and they provide no clue to the author's intention.

Compare the following sample with the one after it and see the difference

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

Improved Version

public static void copyChars(char source[], char destination[]) {
for (int i = 0; i < source.length; i++) {
destination[i] = source[i];
}
}
  • Noise words are another meaningless distinction.

Imagine that you have a Product class. If you have another called ProductInfo or ProductData, you have made the names different
without making them mean anything different. Info and Data are indistinct noise
words like a, an, and the.

Note that there is nothing wrong with using prefix conventions like a and the so long as they make a meaningful distinction.

Noise words are redundant. The word variable should never appear in a variable name. The word table should never appear in a table name. Would a Name ever be a floating point number? If so, it breaks an earlier rule about disinformation.

4- Use Pronounceable Names

If you can’t pronounce it, you can’t discuss it without sounding like an idiot. Can you pronounce this "genymdhms" ? If not , then it would be difficult to discuss this code with your team mates.

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

Now , Imagine this conversation , “Hey, Mikey, take a look at this record! The generation timestamp is set to tomorrow’s date! How can that be?”

5- Use Searchable Names

Try to use names that would be less common to appear in search unless you are really searching for them.

  • If a variable or constant might be seen or used in multiple places in a body of code,
    it is imperative to give it a search-friendly name.
  • Single-letter names can ONLY be used as local variables inside short methods.
  • The name e is a poor choice for any variable for which a programmer might
    need to search. It is the most common letter in the English language and likely to show up in every passage of text in every program.

That is all for this part , in the next part I would complete the other attributes that your names should have. Feel free to add your own advises regarding naming variable and functions. Thanks a lot.

Subscribe to Learn With Passion

Don’t miss out on the latest issues. Sign up now to get access to the library of members-only issues.
jamie@example.com
Subscribe