Clean Code, Meaningful Names (Part 2)

INTRODUCTION

The name of a variable, function, or class, should answer all the big question. It should tell you why it exists, what is does, and how is it used. If a name requires a comment, then the name does not reveal its intent.

int d; // elapsed time in days

The name d reveals nothing. We should choose other names, some things like:

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

We have some rules about naming in programing.

7 RULES

1. Avoid Disinformation

We should avoid words whose entrenched meanings vary from our intended meaning.

Do not refer to a grouping of accounts as an accountList unless it’s actually a List. The word list means something specific to programmers. 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.

2. Make Meaningful Distinctions

You can not use the same name to refer to two different things in the same scope. And if names must be different , then they should also mean thing different.

3. Use Pronounceable Names

Humans are good at words. A significant part of our brain is dedicated to the concept of words. Compare :

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

to

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

4. Use Searchable Names:

Try to user searchable names if you can.

Compare:

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

to

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;
}

5. Member Prefixes

You also don’t need to prefix member variables with m_ anymore. Your classes and functions should be small enough that you don’t need them.

public class Part {
    private String m_dsc; // The textual description
    void setName(String name) {
        m_dsc = name;
    }
}

It should be replaced by:

public class Part {
    String description;
    void setDescription(String description) {
        this.description = description;
    }
}

6. Don't Pun or Be Cute

Will they know what the function named HolyHandGrenade is supposed to do? Sure, it’s cute, but maybe in this case DeleteItems might be a better name.

Don’t use the name whack() to mean kill().

Don’t tell little culture-dependent jokes like eatMyShorts() to mean abort().

7. Add Meaning Context.

This rule give us an advice that how clearly should programmer code. It is "Context"

Compare:

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);
}

to

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";
    }
}

FINAL WORDS

The hardest thing about choosing good names is that it requires good descriptive skills and a shared cultural background. This is a teaching issue rather than a technical, business, or management issue. As a result many people in this field don’t learn to do it very well.

Follow some of these rules. It will pay off in the short term and continue to pay in the long run.

PEACE.