Importance of Intention-Revealing Names in Programming | Clean Code Concepts
Have you ever had hard time to understand what does this variable/function/class does in this code? Did your program ever break because the class/function you are using, is returning unexpected results? I have been there (With my own code 😅 ).
Nothing is more frustrating than spending 15 minutes to debug the problem and later you find out that the function/variable is returning unexpected value. In this blog, we will look into how to name your variables, classes or functions in a way that it reveals the true intention of what it does.
This blog is based on the book called “Clean Code" by Robert C. Martin. I highly recommended every programmer this book as it teaches you a lot of different concepts around writing clean code. This blog is just *one topic* from the whole chapter after “Meaningful Names”. Yes, you heard it, right. Just one topic 😱 ! So Let’s dive in on this topic.
I have created a YouTube Video on this topic! Please check it out and Do not forget to subscribe!
The Problem — What does this code do 🧐 ?
Usually when the new programmers are writing the code, they just focus on the functionality of the code. They just want to write lines to make it working. They do not spend enough time after naming their variables/functions/classes. Most of such programmers think this is just a waste of time. Why would you spend 5 minutes, just to figure out what you should name your class? Because of this mentality, we get memes like these:
The code written by such programmers usually have names that are shorthand, something funny or worst — gives you wrong information. When you are writing your code, for sure these variables make sense and you know what each line is doing, but what about the future? When you will be coming back to after few weeks, to fix that tricky bug, would you be able to understand what does this variable with some funny name means? Would you be able to remember the full form of the short-hand variable you used three weeks ago? And what about someone on your team who is reading the code? He will have no idea on what does the code do. Just because you did not spend 5 minutes to name your variable properly at first place, it is now costing 15 minutes to your team, just to figure out what the heck that variable does.
Using Better and Intention revealing names is an investment for future! it will payback to the someone (including you) is reading the code to fix some important bug or to add a feature with critical deadline. Yes, It is hard to name variables that reveals the true and perfect intention of your code, and it will take a time for now, but it will save tons of time in future!
As a programmers, we should be aware that code is not static. Code grows and changes over time. During this change, your code might change. Your function’s intention will change! If such change happens, rename the function! When you are reading the code, and you can find a better name for that Utility class, change it! To keep your code clean and to make sure the names reveal true intent, you have to take care of names over time! Remember that, writing code or naming is not a one time task!
The Solution — How to name Intention-revealing name 🤔 ?
As we understand the problem now, let’s see how to do Intention-Revealing naming.
If the name answers the following three big questions, we can say that the name reveals the true intention of the code:
- Why does it exists in the program?
- What does it do in the program?
- How is it being used in your program?
If you get the answer of all three questions, the name reveals true intent. Someone can read the name and he/she can say what does this code will do in the program. Please note that you should get the answer of the questions only from the name of variable/function/class. If your code requires comment to answer these questions, It does not reveal the true intention of your code!
Let’s look at the example to get better understanding of this. Read the following line and ask these three questions.
let d; // elapsed time in daysThe variable itself answers none of these questions! You can’t predict how this variable will be used, or what will it store during runtime. it will be worse when you are reading the following code in the class, where every time you see d, you will have to stop for a minute and remember what does this variable do 😓 .
Here are some better alternative for this variable which follows the concept we just learned. If you read these names, you should be able to answer all three questions.
let elapsedTimeInDays;
let daysSinceCreation;
let daysSinceModification;
let fileAgeInDays;Choosing longer, descriptive and intent-revealing names will make it lot easier to write new code and modify existing code without any confusion. Someone might question that, using these long names will decrease my productivity as I have to write more code. But Do You?? This is a lame excuse. Currently, all the IDEs have auto-completion feature. Just time couple letters and it will suggest your defined variable! You just need to click “Enter” and Magic!!! So don’t worry about using longer names if they explains better about what does the code do!
The Case Study
From the first online course I did on programming, I learned the basics about this concept like, not to use short hands, or funny names. Which is why it took me hard to find a code I have written in past, where I could have used better name that reveals the true intention.
Although, I am far from being perfect and I found bunch of places where I violated this concept. I feel like the code I am about to mention will be the best choice for a case study on this concept.
Code: — https://github.com/harshPPatel/expense-tracker-app/blob/master/server/models/Statement.js
In this file, here is the code from Line 11 and Line 13.
// Getting month and year
const month = options.month
? options.month - 1
: date.getMonth(); // value of date here is: new Date();const year = options.year
? options.year
: date.getFullYear();
Let’s try to answer three questions for these two variables.
Why does it exists in the program?
From the names of these variables, we can say that it stores value of month and year of some kind. But we can not really say “Why” it exists.
What does it do in the program?
We are performing some king of logic on the values of these variables, but we can not predict what will these variable do further in the code
How is it being used in your program?
Again, we are not able to answer this question either.
These are bad names for variables. Yes, if I read the code, I know where these will be used, but you might had bit hard to understand what is happening. While I was reading the Clean Code book, I was also learning NestJS where I re-wrote this app in NestJS to understand the concepts of this framework. Here are the names that I used in my re-write:
const queryMonth = month ? month - 1 : date.getMonth();
const queryYear = year ? year : date.getFullYear();These names now make bit more sense and can answer two questions:
What does it do in the program?
- it performs some logic to create a month to make some kind of query.
How is it being used in the program?
It will be used as some kind of variables to query data.
Although these names are not perfect either. they do not answer the first question. If you have noticed the code closely, we can see that it does not return month, but it returns the index of the month. From my understanding of this concept, the best name I can think about for these variables will be as following which will answer the first question as well:
const queryMonthIndex = month ? month - 1 : date.getMonth();
const queryYearIndex = year ? year : date.getFullYear()Thank you for reading my blog till the end! If you liked what I wrote in this blog, please give it a clap! It helps me a lot! Make sure you follow me so that you are notified when I post new blog.
If you have any question or want to discuss more about this, drop a comment and I will reach out as soon as possible! Also let me know in the comment if I should keep writing detailed blogs like this one, which are based on different concepts from Clean Code book.
References
- Please note that the first example I mentioned (
let d;), came directly from the Clean Code book by Robert C. Martin. - Original Case Study project: https://github.com/harshPPatel/expense-tracker-app/
- Rewrite of my old project: https://github.com/harshPPatel/expense-tracker-nestjs/
- The Meme is from Reddit: https://www.reddit.com/r/ProgrammerHumor/comments/98sqd0/when_you_have_to_choose_a_variable_name/
- Clean Code Book by Robert C Martin: https://www.amazon.ca/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882
