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 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.
Avoid disinformation
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 Product , ProductData and 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 addressStreet , addressCity , 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. Customers , 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 get , fetch , 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 detectShortestPath , 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 street , city , 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 addrStreet , addrCity and addrCountry as the variable names.
Please read my next article — Part 3: Functions to know how to write clean functions.