If you are a "true" developer, then you"ve heard about "Clean Code" written by Robert C. Martin. In many companies, this book has become part of the developer"s bible. In combination with "Clean Coder", I would say that these two books are mandatory for all developers.
I will start a series of articles related to this topic. If you"ve already read this book, then it is a good occasion to refresh your memory. For others, it is the perfect moment to discover how good code should look like. All the main ideas are from "Clean Code". You can look at this series of articles as a summary of the book itself.
I decided to start writing about this topic because there are things that need to be remembered and reviewed from time to time. "Clean Code" is the kind of book that you don"t read once and throw it in a dark corner of your room.
This is the kind of book that you read again and again. Every time you will discover new things that you missed or things that are revealing to you in different ways.
This is the first topic that we will cover in this article. A good name can replace one page documentation and can help another developer to understand the application and find an issue in a shorter period of time.
Everything in an application has a name, from a trivial field to a method or component name. A developer needs to handle the code through names. This is why it is important to give and use good naming.
How many times have you looked over the code that you wrote three months before and you didn"t remember what you did there? This is why good naming is a must.
A good name can save you 10 minutes of debugging or 20 minutes of searching in documentation. When we look over the code, the code should reveal itself. Even the most complex algorithm should be easy to read if you have a good naming.
A name of the field, method, class or component should tell us why it was created, what its main purpose "in life" is. We can find below the classic example that is given when we talk about this topic.
DateTime d;
DateTime dn;
DateTime dlr;If we look over these field definitions or if we see them somewhere in our code, we would have no idea what these fields represent and why they were used (created).
DateTime creatingDate;
DateTime currentDate;
DateTime timeFromLastRun;The above naming gives us more information about our fields. It is clear for us what the purpose of each field is and what kind of information it provides.
We should never use a name that is mythical or hides the purpose of a specific resource. Don"t forget that a long name doesn"t affect application performance. Yes, it is true that in some languages it can increase the size of the application, but nowadays, space is not a problem - it is more expensive to have a support team that doesn"t understand a part of the application.
Finding a good name can take time, but this can save us time afterwards. Since finding good names is pretty hard, it is pretty easy to end up with names that are already consecrated. For example, using names as "hp", "cmd" or "sco" is bad. These are names that are already used as commands by the operating system.
When you pick a name that is already used in another context you should take care to use it in the same context or with the same meaning. Never use consecrated names in other purposes.
carList
houseListWhat do you see in the above examples? The "List" suffix is telling us that the variable is a collection of cars or houses. If the variable represents only a car or a house, then the name is misinforming. Also, there are times when "List" is used even if it uses an array or other types of collections.
Another important thing is naming fields in a similar way. For instance, in the below example we have two fields that are different only in one letter or other two fields that are very long and spotting the difference is not easy.
cars
car
optimizelViewConfigurationUsingAVirtualProcess
optimizeIViewConfigurationUsingBVirtualProcessIn the example related to "car(s)", finding a name like "currentCar" and "carCollection" could help us more to understand their purpose.
Avoid using characters that are similar like "L" lower case ("l") and "I" upper case or "0" (Zero) and "O" ("o" upper case). It is extremely hard to spot the difference between them. In the above example, related to long naming, the first letter after "optimize" is not the same.
In an application you can easily end up with naming that is similar, even if you tried to make a clear distinction between them. Because of this, we can end up misspelling a word or adding numbers at the end of the name.
In the example below we have a method that converts a string from one format to another.
void Convert(string s1, string s2)The name of the input parameters don"t help us to understand the logic. Replacing "s1" with "input" or "inputInXYZFormat" and "s2" with "output" or "converted" or "outputInABCFormat" would help us more.
When we don"t have ideas to name a class, we can easily end up with 3 classes with the following names:
Car
CarData
CarInfoThe problem with this naming is that there is no clear distinction between "Data" and "Info". The reader will not know what kind of information each class has.
Using suffixes or prefixes that represent the type of the field doesn"t help us to make a more readable code. What is the difference between "Name" and "StringName" or "NameString"? There is no difference in the end. A name like "CarName" would be more useful. The same thing applies to method, properties and class naming.
Even if code is written for machines (010101001), it is pretty sure that you end up during debugging or refactoring to talk with another person about that code. It would sound pretty silly to name a field in a way that you cannot read or to use a naming that is coded.
"carN4RegS1" - "carNumberForRegistrationSection1"
"dtoCRcrd100" - "car"Sounds stupid? No.
You need to search the code to see the different fields used. Yes, it is true that the new IDE"s can make the job for us, but we still have to use names that can be easily searched.
For example, how easy it is to find where "i" or "j" was used. The same thing is happening with magic words that are used inline, without extracting them as constants.
For example searching and replacing a number value in an application can be a nightmare if the same value was used in line for different use cases.
Don"t try to reinvent the wheel and define your own encoding for things that were already defined and standardized. The last thing that you want to have is your own custom language.
Because of this, try to use prefix like "I" for interfaces or "Base" suffix for abstract classes. Don"t use "C" prefix for class implementation or "m_" for variables.
If you end up with a custom encoding, take a step back and try to see why you have ended up in this situation. Based on that response, you should make a decision.
Let"s start with an example:
r
t
pEven if we are developers, we don"t want to learn and memorize that "r" means full url of Dacia server from Romania, "t" is the same url but without protocol information and "p" represent the query parameters that we need to send to the server to be able to login.
Even if mental mapping is bad, there are some names that are standard in our days. For example, when we see an "i" or "j" we know from the first moment that we are talking about an iteration.
There are two simple rules that can help us a lot when we need to find a good name to our class or methods:
Try to avoid naming classes with prefixes/suffixes like "Service", "Factory", "Processor", "Data", "Info". These class names are overused (especially when we don"t find better names).
One and the same concept in your system should have the same name. Be consistent from this perspective. You don"t want to end up with two names of a class that express the same concept. For example "Processor" and "Analyzer" or "Controller" and "Manager".
Using the same word per concept will help developers to understand the code more easily.
Don"t use names that are out of context and are not from that specific domain. It is more natural for someone that works in automotive industry to use "engine" and not "power source". You should use the specific domain names and not developers naming, that can be wrong.
This can be a cause of misunderstanding between clients and developers.
It is pretty easy to add context to things that are already clear. For example in a class called "Car" you don"t need to name the color field of the class "carColor" or "colorCar". You are already in the car class and all information from this class is related to "Car".
Finding good names inside an application can be a hard and time consuming thing. It is not simple to find good names. Because of this, you should invest time to find and use good names.
One difference between a smart programmer and a professional programmer is that the professional understands that clarity is king. Professionals use their powers for good and write code that others can understand.
Robert C. Martin (2008-07-31 21:00:00+00:00). Clean Code: A Handbook of Agile Software Craftsmanship (Kindle Locations 969-970). Pearson Education. Kindle Edition.
by Sorin Pânca
by Radu Murzea
