Clean Code Chapter 2 — Meaningful Names Summary

Reveal the Code Intention With Meaningful Names

Photo by Ed Robertson on Unsplash

Introduction

This is part of my personal reading summary of the book — Clean Code.

• Clean Code Chapter 1 Summary

Before starting chapter 2, let’s ask yourself

What are meaningful names mean to you?

• Are meaningful names refer to something which is clear & straightforward?
• Are meaningful names refer to something which doesn’t raise a question mark inside your head after you read it?

Below are some definitions of what meaningful names from the book resonate with me the most.

1. Reveal Intention
2. Avoid mental mapping
3. Use Noun for Class Name & Method Name should have Verb
4. One word per concept

Reveal Intention

A meaningful name should be able to reveal the intention. For this section, I will be providing 3 different scenarios in variable naming,

• Poor Variable Naming
• Poor Variable Naming with Descriptive Comment
• Good & Clear Variable Naming
• Pronounceable Name

Let’s start with Variable Naming.

Poor Variable Naming

const d = 24 * 60 * 60;

From the above code, we basically have no idea what is d means to us? Even the code author might even forget about it after a period of time. We knew that the result is 24 * 60 * 60. But we definitely do not know what it represents. Therefore, we are unable to reuse and maintain it.

Poor Variable Naming with Descriptive Comment

However, some might say we could simply add the comment to the code and it could bridge the gap of misunderstanding such as the code below.

const d = 24 * 60 * 60; // Day in seconds

However, this is still not the most ideal solution. Because every time when I need to use variable d, I would have to go back to the variable definition and check the comment. This would require context switching and cost our mental energy.

Good & Clear Variable Naming

The most ideal approach is to use a proper variable name that reveals the intention of the variable. In this case, the variable is named as dayInSeconds.

This is straightforward and I could easily know what dayInSeconds do at a glance.

const dayInSeconds = 24 * 60 * 60;

This does not only apply to the variable name, but it should also apply to the function name, class name, and every possible piece of code to keep our codebase clean. Try to Imagine the same function given 2 choices for the function name, getData and getTransactions .

getTransactions definitely more clear and straightforward here while getData left you full of a room of imagination such as What kind of data?

Pronounceable Name

Typically, a pronounceable name is easy to reveal the intention. If you’re unable to pronounce it, you hardly can discuss it with your co-worker. Therefore, a pronounceable name is always better in communicating intention.

Avoid Mental Mapping

This is one of the points that I agree with very much. A lot of times, programmers tend to use variable names that require mental juggling.

The worst variable naming provided from the book is single-letter variable names such as a , and b. We mostly use this in for loop. This normally still works ok within for loop if the logic remains simple. But still, a single-letter variable name is the worst choice most of the time.

This is one of the great quotes from the book.

Difference between a smart programmer and a professional programmer is that the professional understands clarity is king. Professional use their powers for godd and write code that others can understand. — Clean Code Chapter 2

The above quote serves as a good reminder for me. Certainly, building features and writing code is a daily job for a programmer. But that’s not enough, we gotta be professional about it. We need to write code in a way that others can understand.

Most of the projects usually have more than 1 developer, so writing code in a way that people can understand will make the productivity grow faster and easier collaboration. Otherwise, I believe it could slow down the productivity as the team grows because now everyone is writing things which they only understand themselves. Team members now have to waste time understanding each other’s code.

Use Noun for Class Name & Method Name should have Verb

We should use noun for a class name such as Customer, Product and Transaction. While method names should have verbs in them such as updateAddress. The below simple example is how we should write our class name and method name.

class Customerclass Customer {
  // Verb "update" in function name
  updateName(firstName, lastName)
}

One Word Per Concept

Using one word per concept here is crucial. Try to imagine if you have 2 components with similar role. However, the 1st component is named as UserController while the other one is TransactionManager.

If you’re the new member of the team, you’re confused. Now you faced the dilemma and you start questioning yourself:

• What is the difference between Controller and Manager?
• Why do they have different kinds of concept names when they have the same role in the codebase?
• Worst, you thought this might be some new programming concept and try to spend your time and google them. “Controller vs Manager”.

So, don’t confuse yourself and others. Just pick 1 word per concept and stick to them all the time.

Conclusion

To me, the most important point in this chapter is really about how to reveal the intention of your code in a clear and straightforward way. Meaningful names play the most crucial role here.

However, meaningful names don’t come easy. Sometimes, it took time and several refactor to get it. So take your time in the process.

Simple Actionable Step

Open your codebase now and see if there is any variable or function you could rename for better clarity and understanding.

Notice

This post is part of the reading summary that I wrote in Gitbook. You could read the Gitbook here.

GitBook

Feel free to give me any constructive feedback and suggestion in case I am missing out on something truly important from the book.

I hope you enjoy it and thanks for reading.