Clean Code Naming Conventions
Treat naming conventions as the name of your baby. Don’t use the name of Elon’s son….
I’ve been reading Clean Code recently which was recommended by my Tech Lead, written by prolific Robert C Martin, also known as “Uncle Bob”. It has been one of my life’s most delightful and eye-opening experiences as a developer. There have been lots of amazing takeaways from the book and I highly recommend it to anyone wishing to become a better programmer rather than become a programmer. Because everyone can be a programmer, but few of them can be a good programmer.
What is the difference between Programming and Good Programming?
Programming is what we have all been doing. Now is the time to do good programming. We all know that even the bad code works. But it takes time and resources to make a program good. Moreover, other developers mock you when they are trying to find what all is happening in your code. But it’s never too late to care for your programs.
“Any fool can write code that a computer can understand. Good programmers write code that humans can understand” — Martin fowler
“Quality means doing it right when no one is looking” — Henry Ford
Clean code makes other developers also understandable rather than the original author of that code. Readability, changeability, extensibility, and maintainability come with the understandability of the code.
The first thing you can consider when you are coding is naming. Names are all over the software. When coding, you should consider naming variables, functions, arguments, classes, packages, source files, and directories that contain those source files, etc. If you are going to maintain some naming standards inside your code, let every developer know about that.
You can introduce several VSCode plugins like ESLint, Prettier+ESLint — Code formatter + Linter, Bracket Pair Colorizer, Beautify, Code Spell Checker, TypeLens, npm Intellisense, and GitLens, etc for your team. Having a linter helps you write clean, beautiful code that is also easier for others to read.
According to the first chapter of the book, there are some standards for naming,
1. Choose descriptive and unambiguous names.
2. Make meaningful distinctions.
3. Use pronounceable names.
4. Use searchable names.
5. Replace magic numbers with named constants.
6. Avoid encodings. Don’t append prefixes or type information.
Choosing the correct name for a function or variable requires many hours of reading experience and codes. This challenge requires a lot of practice. So let's go deeper with the naming convention standards.
1. Choose descriptive and unambiguous names.
As an example, use a descriptive name for an intent that can reveal its intention. It will get some time to choose suitable names, but it will save more time than it takes right now.
When you are naming consider below 3 questions when you are naming variables, functions or classes and try to get the answers via the name;
- Why it exists?
- What does it do?
- How it is used?
Other than that, when you naming classes, use nouns and adjectives like Customer, Product, and Student, etc. If it is a function or method, use verbs like getName, getTotalCount, setProductName and addCustomerName etc.
If it is a variable, don’t use a single letter like below example;
let d; //available leave balance.
Here, the name “d” reveals nothing and it needs a comment because the name doesn’t reveal it’s intent properly. We should choose a name that specifies what is being measured and the unit of that measurement:
let availableLeaveBalance;
You can use a single letter inside a for-loop for loop counter. As for-loop tradition , that also uses most of the time i,j, and k letters only.
2. Make meaningful distinctions.
Use the same word for the same purpose across the codebase.
FetchValue() vs GetValue() vs RetrieveValue()
What’s the difference between fetch/get/retrieve anyway?!
If you are using fetchValue() to return a value of something, use the same concept; instead of using fetchValue() in all the code, using getValue(), retrieveValue() will confuse the reader.
3. Use pronounceable and searchable names.
And another thing is, use words which can be pronounced rather than using non-pronounceable words like this example.
let genymdhms; // generation timestamp
These kinds of variables names are hard to pronounce and no one will be able to remember them, aside from the writer themself. So better naming makes scaling easier.
can be used: let generationTimeStamp;
4. Replace magic numbers with named constants.
Another point is, when you are using some constant values, define them using searchable words like the below example. It gives more understandable to other developers.
const MAX_IMAGE_WIDTH = 100;
const HOURS_PER_DAY = 24;
5. Avoid encodings. Don’t append prefixes or type information.
And also rather than using terms with a strong sense distinct from what we want to say (disinformation) and unnecessary encodings of data types along with the variable name like the below examples:
let accountList; // Eg: Disinformation
let nameString; // Eg: Encoding
let salaryFloat;
You can use:
let accounts;
let name;
let salary;
Because there is no need to mention the data type in the name.
6. Don’t Be Offensive/Cute
Don’t be a serial killer behind your code
function killThemAll();
function whack();
Names you use for your functions will be read by many people. If you use words like kill, whack, and throw, it will not give a good image of the developer.
Naming convention should be generic, and as professional as possible, and should not include any cultural slang.
So you can write it like ;
function removeAll();
function deleteItem();
7. Be Positive
Try to show the positiveness via your coding. So try to use words like these;
isDisabled should become isEnabled
shouldNotShow should become shouldShow
As humans, we have a better understanding of the positive approach so we should use them in the names we pick.
To write good code, you have to care about it. To become a better programmer you must invest time and effort.
