This article is in continuation of my previous article Summary of — Clean Code by Robert C Martin — Part 1: Overview. Please buy the book from Amazon if you want to know more in detail about how to write meaningful names.
Importance of naming
Names are everywhere in software. We name our variables, functions, classes, and packages. Naming is one of the most crucial parts of clean code. To write code in an existing codebase, we always read the code and then change it. As per a survey, the reading vs writing time ratio is 10:1 for an average developer in a software company. There are some basic principles you must follow before you think of the name in your code.
Use Intention Revealing names
Instead of writing
int d; // total count of students it is always better to write
int studentCount; . If your variable requires a comment in the description, it is not a good name.
Don’t simply call a group of student objects as
studentList . For most of the developers
List has a different meaning. List, in general, is short of ArrayList for most Java developers. Instead, use
studentGroup or just
students as the variable name.
Make meaningful distinctions
Number series naming
(a1, a2, a3, ..., aN) is the opposite of intentional naming. Such names are not dis-informative, they are non-informative. They provide no clue of the code author’s intention.
Remove the usage of noise words as they are redundant. Classes with names
ProductInfo have the same meaning. A variable
nameis better than
nameString because we know names are always String.
Use Pronounceable Names
It is always easy to talk about code and convey others if we use pronounceable names.
Use Searchable Names
A good searchable name is always suggested over a single letter variable name. You can use a variable
String linkedInURL; instead of
String l; . Now when most of the modern IDEs support the suggestion of variable names and methods in sorted order, naming a series of variables like
addressState is really helpful in autosuggest.
Avoid Mental Mapping
Us developers are smart. If we see some code as
int a, b; , we will automatically choose the next variable name as
int c; . We must avoid this and use the best practices to choose a better name.
Choosing a Class Name
Always choose a noun or noun phrase for a class name. Eg.
WikiPage . Avoid verbs as class names.
Choosing a Method Name
Choose a verb or verb phrase as a method name. As it helps in understanding what it does.
When class constructors are overloaded, use static factory methods with names that describe the argument.
Complex decimalPoint = Complex.FromDecimalNumbers(30); is better than writing
Complex decimalPoint = new Complex(30);
Don’t try to be cute while naming
You must never use slang in a variable name. Your sense of humor may not be understood by everyone.
Pick one word per concept
It is confusing to have
retrieve in the different classes.
When you use the same name across all classes, try to keep the behavior/return type also the same. Eg.
add function should always return a list of objects in all classes.
Use Solution/Problem domain names
Most of the readers of your code would be computer-science students in past. So if you use
detectRaceCondition as a method name, they will understand it in a better way.
Add meaningful context to your names
In a method, if you use the variables as
country for storing some address values, a variable with a name
state is automatically attached to address syntax but would have been used in a different context. It is always better to add meaningful context like
addrCountry as the variable names.
Please read my next article — Part 3: Functions to know how to write clean functions.