Clean Variables
Clean Code @ Borda: Volume I
Defining variables is the smallest but a fundamental part of clean code approach. If a developer doesn’t follow the clean code principles for defining variables, all other attempts would be futile. They should be written clean from the beginning and remember Dave LeBlanc’s words: “Later equals never”. This article aims to make you understand the importance of variables and guide you to write clean variables.
Simple and meaningful naming
“You should name a variable using the same care with which you name a first-born child.”
Robert C. Martin
Naming is the first step of clean code principles. Let me show how naming affects code.
As you see, naming is important. It helps you figure out how code works. There are some bullet points which we care about. Let’s examine them.
- The meaning of variable names should be crystal clear. The naming must not require any comment. For example, If the variable is a collection of data, then the name of the variable should be plural.
- Naming should be straightforward as possible, don’t find yourself writing over-descriptive names.
- Some words are used for many concepts, such as data, group, and list. Such words should not be used on their own.
- Do not use redundant words for your variables. If the class carrying the entity name is like “Category”, the attribute of the class should not name as “CategoryName”; instead, the “Name” is simple and meaningful enough.
- Avoid using the magic numbers; use constant and enum.
- Using searchable names makes maintenance easier. I know the “searchable name” does not ring a bell. Let me explain myself. Not using abbreviated words or implicit words would be the perfect starting. Other than that, using domain names would help the developer to make connections and look for that word. Using constant and enum also helps for this aim.
- Consistency is an essential property in a clean code approach. Consistency makes sure that each team member will have the same understanding by using the same keywords; such as if one developer uses the “add” word but the other uses the “insert” word, it will not be consistent. To avoid these misunderstandings each word’s usage can be limited to one purpose. Meanwhile, this strategy makes the product readable and, in that way, makes the specific word searchable.
Formatting and Commenting
Formatting is similar to punctuation. The aim of both is to make expression clear and avoid misunderstanding. The team should define the rules as language. Each language has its own rules. These rules should be an outcome of the collective mind, but also each environment has its suggestions, and the team may inspire by them. For example, this link provides best practices for C# environment.
The second would be to define some rules according to the access modifier of variable and keyword. It is going to help you to figure out the variable’s specification.
The final suggestion is using .editorconfig would be a good idea for your project and helps to provide that be sure applied to rules. StyleCop is a robust library I recommend that you look at. Let’s check an example of .editorconfig file for dotnet.
Commenting on variables may be an awful idea. If you need to put some comments on a variable, maybe renaming the variable could be a better idea. However, for being explicit, comments are helpful options regex or DateTime format or decimal format.
For the next chapter please follow this link.
