The Art of Naming: A Guide to Clarity in Software Development

Photo by Nubelson Fernandes on Unsplash

“The beginning of wisdom is to call things by their proper name.” — Confucius

In the vast world of software development, where lines of code intertwine to create variables, functions, classes, or modules, there exists a seemingly simple yet highly challenging aspect: the art of naming things.

At first glance, it may seem trivial, but things (such as applications, subsystems, modules, functions, variables) should be named according to the role they play in the code. This means that when you create something, one needs to pause and think, ‘What is my motivation for creating this?’ To address this topic, we delved into three books:

• Clean Code
• The Pragmatic Programmer
• Refactoring

Index:

1. Use names that reveal their intention
2. Avoid misinformation
3. Make meaningful distinctions
4. Use pronounceable names
5. Use searchable names
6. Class names
7. Method names
8. Don’t be cute

The names are everything in software; because we use them so much, it’s better that we get them right.

1. Use names that reveal their intention

The name of a variable, function, or class, should answer all the big questions. It should tell you why it exists, what it does and how it is used.

int d; // elapsed time in days

The name ‘d’ reveals nothing. It doesn’t evoke a sense of elapsed timer days passed. We should choose a name that specifies what it’s being measured and the unit of measurement.

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

2. Avoid misinformation

The programmers should avoid leaving false clues that obscure the meaning of the code. We should steer clear of words whose entrenched meanings differ from the meanings we intended.

Examples:

hp, aix, sco would be poor variable names because these are names or variants of Unix platforms. Even if you’re programming a hypotenuse and “hp” seems like a good abbreviation, it can be misleading.

3. Make meaningful distinctions.

Because you cannot use the same name to refer to two different things in the same scope, you might be tempted to arbitrarily change a name. It is not sufficient to add a series of numbers or random words, even if the compiler allows it. If the names must be different, then ithey should also mean something different.

Example:

The naming of a number series (a_1, a_2,…, a_n) is the opposite of naming with intent. Such names are not just uninformative; they are non-informative and do not provide clues about the author’s intention. Consider:

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

This function reads much better if ‘source’ and ‘destination’ are used as the names of the arguments:

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

4. Use pronounceable names

If you can’t pronounce it, you can’t argue about it without sounding like a total idiot.

“Well, here in the class dee-tee-ar-cee-are-dee one hundred and two, we have a pee ess zee kyew int, see?” This matters because programming is a social activity.

Compare:

class DtaRcrd102 {
  private Date genymdms;
  private Date modymdms;
  private final String pszqint = "102";
  /*…*/
}

to:

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

An intelligent conversation is now possible: “Hey, Pedro, look at this record! The variable ‘generationTimestamp’ has tomorrow’s date! How could this happen?”

5. Use searchable names

Single-letter names or numeric constants have a particular issue in that they are not easy to locate throughout the body of the code.

Likewise, the name ‘e’ is a poor choice for any variable a programmer needs to find:

It is a common letter and is likely to appear in many text passages in any program.

In this regard, longer names prevail over shorter names, and names that are searchable win over a constant in the code.

The length of a name should correspond to the size of its scope.

If a variable or constant can be seen or used in multiple places in the code, it is imperative to give it an easily searchable name.

Compare:

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

to:

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

Note that the variable ‘sum’ above is not particularly a helpful name, but at least it is easy to find. Furthermore, the intentionally named code makes the function longer, but consider how easy it will be to find ‘WORK_DAYS_PER_WEEK’ compared to finding all the places where 5 was used.

“One difference between a smart programmer and a professional programmer is that the professional understands that clarity is key. Professionals use their powers for good and write code that others can understand.”

6. Class names

Classes and objects should have a name that is a noun or a nominal phrase, such as ‘Customer,’ ‘WikiPage,’ ‘Account,’ or ‘AddressParser.’

Avoid words like ‘Manager,’ ‘Processor,’ ‘Data,’ or ‘Info’ in the class name. A class name should not be a verb.

7. Method names

Methods should have names that are verbs or verb phrases, such as ‘postPayment,’ ‘deletePage,’ or ‘save.’

Accessors, mutators, and predicates should be named for their value and prefixed with ‘get,’ ‘set,’ and ‘is’ according to the JavaBean standard.

Example:

String name = employee.getName();
customer.setName("Pedro");
if (paycheck.isPosted()) { … }

When constructors are overloaded, use static factory methods with names that describe the argument.

Example:

Complex fulcrumPoint = Complex.fromRealNumber(23.0);

It is generally better than:

Complex fulcrumPoint = new Complex(23.0);

Consider enforcing this by leaving the corresponding constructors private.

8. Don’t be cute

Choose clarity over entertainment value. Will others know what the function called ‘holyHandGrenade’ is supposed to do? Sure, it’s cute, but maybe in this case ‘deleteItems’ could be a better name.

Cuteness in code often appears in the form of colloquialisms or slang. For example, don’t use the name ‘whack()’ to mean ‘kill()’. Avoid small culture-dependent jokes like ‘eatMyShorts()’ to mean ‘abort()’.

Say what you mean. Have intent in what you say.

Acknowledgments: The author acknowledges that this article was partially generated by ChatGPT (powered by OpenAI’s GPT-4 language model; http://openai.com). Editing and research were conducted by the author.

9. Bibliographic references

[1] Martin, R. C. (2009). Clean code: a handbook of agile software craftsmanship. Pearson Education.

[2] Thomas, D., & Hunt, A. (2019). The pragmatic programmer. Addison-Wesley Professional.

[3] Fowler, M. (2019). Refactoring. Addison-Wesley Professional.