Introduction

As a developer, you've probably encountered code where variables, functions, or classes have obscure names like toto, foo, or bar.

Although this might seem trivial or like a simple shortcut, it is one of the most costly mistakes in terms of code maintainability and readability.

If you've heard of the book Clean Code by Robert C. Martin aka Uncle Bob, you might know that one of its chapters deals with the importance of meaningful naming in code.

This article will explain why this practice is crucial and how to apply it to your own work.

What is Meaningful Naming?

A meaningful name is simply one that reveals intent.

This means that the name of a variable, function, or class should clearly and precisely describe what the element represents or does.

In an ideal world, a developer reading your code shouldn’t need to dig into the details of a function or trace every line of code to understand its purpose.

Let’s take an example:

// Bad example
let d: number

// Good example
let elapsedTimeInDays: number

In this example, d is a vague name that gives no information about what the variable represents.

On the other hand, elapsedTimeInDays is a name that immediately communicates its intent: it's the elapsed time in days.

By choosing a meaningful name, you instantly improve code readability.

Consequences of poor naming :

Names that are not explicit can cause short-, medium-, and long-term problems:

• Increased time to understand : When you or another developer need to revisit this code months or years later, a vague or misleading name can make the understanding process tedious. You might need to dig through the code to figure out what each entity does.

• Misinterpretation errors : A bad name can lead to misinterpretation and misuse of a feature. For example, naming an array accountList when it is actually an array, not a list, can create confusion about the data structure used.

• Difficult maintenance : As a project grows more complex, maintaining code with unclear names becomes more challenging. Clean code with meaningful names is easier to update and evolve.

Rules for choosing a good naming convention :

1. Reveal intent :

A good name should make the function or role of an entity clear without having to dive into implementation details. It should be instantaneous.

// Bad example
let t: number[]

// Good example
let transactionAmounts: number[]

In this example, t tells us nothing, whereas transactionAmounts clearly states what the list contains.

2. Avoid abbreviations :

Abbreviations, while they may seem convenient, harm readability. Unless the abbreviation is an industry standard, it’s best to use complete names.

// Bad example
let usrCnt: number

// Good example
let userCount: number

3. Pay attention to consistency :

Consistency in naming across a project is crucial. If you use fetchUserData in one place, don’t name the same function retrieveUserData elsewhere.

Maintaining consistent terminology improves the understanding of the overall project.

4. Use appropriate names for scope :

For variables with a short scope (for example, local variables in a function), shorter names might be sufficient, while for variables with a broader scope, more descriptive names are recommended.

// For a local variable
for (let i = 0; i < 10; i++) { ... }

// For a global or class member variable
let maximumUserAge: number;

5. Avoid technical terms in names :

It is discouraged to encode technical details in names, like the data structure type or other implementation specifics.

For example, adding suffixes like List, Data, or Info can make names cumbersome and unnecessary if the information is already clear from the context.

// Bad example
let accountList: number[]

// Good example
let accounts: number[]

6. Make names easy to search :

Choosing names that are too short or too generic makes searching through the code difficult. Using specific names facilitates navigation in large projects.

// Bad example
let max: number

// Good example
let maximumAllowedConnections: number

Conclusion

Choosing meaningful names is a key skill for every developer.

Though it might seem secondary, it significantly improves the quality, readability, and maintainability of code.

By following the advice from Clean Code, you can transform the way you code and make your projects easier to understand, for yourself and for others.

It is often said that "code is read more often than it is written."

With that in mind, investing time in choosing the right names is a long-term investment in the quality of your codebase.