Summary of — Clean Code by Robert C Martin — Part 2: Meaningful Names
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 a software. We name our variables, functions, classes and packages. Naming is one of the most crucial part of clean code. To write code in an existing codebase, we always read the code and then change it. As per a survey, 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 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 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 of the Java developers. Instead use
studentGroup or just
students as the variable name.
Make meaningful distinctions
Number series naming
(a1, a2, a3, ..., aN) is opposite of intentional naming. Such names are not dis-informative, they are non-informative. They provide no clue of code author’s intention.
Remove the usage of noise words as they are redundant. Classes with names
ProductInfo have 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 suggestion of variable names and methods in a sorted order, naming a series of variables like
addressState is really helpful in autosuggest.
Avoid Mental Mapping
We 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 describes 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 a slang in a variable name. Your sense of humour may not be understood to everyone.
Pick one word per concept
It is confusing to have
retrieve in different classes.
When you use a same name across all classes, try to keep the behaviour/return type also 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 a computer science student 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 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.