Clean code o código limpio

The Art of Clean Coding: The Power of Meaningful Names

Clean code is a programming practice based on writing clear, readable and maintainable code. It consists of rules on how to write code. Among them are: style rules such as: avoiding redundancies, keeping functions and methods to a few lines and writing comments only when necessary, among others.

One of these rules is to take care of the nomenclature of our code for variables, functions, classes…etc. The idea is to use correct names so as not to depend on documentation or comments that mess up the code and, in addition, would require extra maintenance. With this set of clean code rules, we should be able to read the code easily, as if it were a programmer’s book. Choosing the right names may take time, but it is worth it, as it will actually speed up the work.

PRINCIPIOS MÁS IMPORTANTES DEL CLEAN CODE O CÓDIGO LIMPIO

There are a number of style rules that will help us to have meaningful names in our code. Some of the ones we think are most important are as follows:

USE SELF-DESCRIPTIVE NAMES

Let’s remember that what we want to do is to dispense with additional comments that add complexity to the reading of our code. To do this, the first and most important thing is that the names we use are self-explanatory. If when reading the name of our variable we already know what it is used for, no additional comments are needed. Simple, isn’t it?

For example, let’s suppose we want to store the number of days a user has been unmodified. In our code we have it in the following variable: int d;

But we can find a much better name, that explains what is the value that it stores, for example: int daysSinceLastModification;

In this way, it will not be necessary to discuss what a variable stores or what it is used for. When we come back to that part of the code after a while, we can simply read it and understand it. The same applies for functions and classes, it is not as clear user.GetThem() as user.GetAllBooks().

Clean code o código limpio

AVOID MISINFORMATION ON NAMES

If in the previous point we have managed to give value and meaning to our names, the next step is that we must not confuse the reader.

As programmers we should avoid abbreviations in names. These may seem like a good idea at the time of writing the code, but in the long run they will cause confusion. If for example we have the variable addressDt, the Dt part can be confusing. What does Dt mean? If we are also working with ADO.NET, will it be DataTable?

In order not to create this kind of confusion, we should avoid abbreviations and write the complete variable: addressDetail.

In addition, in this example we have seen that there are certain keywords that mean something more to programmers, as is the case of DataTable. Avoid adding keywords like DataTable or List if the variable is not really a DataTable or List.

WRITE NAMES YOU CAN PRONOUNCE

As humans, we are closely related to the use of language. A large part of our brain is dedicated to the concept of language. Therefore, it makes sense that the names we create in our code are as easily pronounceable as words are in our language.

Let’s take an example. Let’s suppose we have a variable that stores the quantity we have of a product. If we call this variable prodQnty we will most likely end up reading it something like ‘prodty’ or ‘prodcunty’. So if we are having a discussion about that part of the code with our teammate, we won’t be able to pronounce this variable without sounding like an idiot.

However, if we change the name of the variable to productQuantity, we can now have a serious conversation about the changes we want to apply to that code.

USE SEARCHABLE NAMES

Throughout the day, as programmers, we are going to do a lot of searches in the code. You don’t realise how badly chosen a name is until the search you’re trying doesn’t make it easy for you to find that function, variable… etc.

The average application will end up being an ocean of letters sooner or later. For that reason, looking for the exact name of the variable we want, if it is not well defined, can be like looking for a needle in a haystack.

Searching for WORK_DAYS_PER_WEEK will not be the same as searching for WORK_DAYS_PER_WEEK as the number 5 in the code.

The length of a name should be directly related to its scope. If we have an Enum with the working days of the week, imagine how messy it can be to search for use cases using the letter ‘d’. However, we can finish a lot faster if we have given it a name like WorkingDays.

At the other extreme, for a numeric variable that is going to help us iterate a for loop, there is no problem with naming it with the letter ‘i’ since it will be used in a very small context. Moreover, in this case it is already a global convention in programming.

METHOD AND CLASS NAMES

The names for classes and methods have a convention within the clean code rule set. These are fairly straightforward:

  • For class names we will use nouns or noun phrases such as Customer, Product, UserAccount. A class name must not contain a verb.
  • Methods, on the other hand, should have verb names. Perfect method names for the above classes could be: getName, hasStock and signOut.

ONE WORD PER CONCEPT

Choose a word for each concept and commit to it. You must maintain the coherence of each action or abstract concept you have in your code.

For example, let’s say we have a User class, to which, as we already know how to give perfect method names, we add the saveNewPassword method. So far so good. Later, we work on a Bank class and we need to add a method to store movements in the bank accounts. Now we choose to call the writeMovement method.

This kind of inconsistency is what we need to avoid. Someone coming from working with our User class and moving to the Bank class will expect the correct method to be saveMovement. So for each concept in the code, we should choose a word and stick with it.

USING SOLUTION DOMAIN NAMES

Readers of your code will be more programmers. The best thing you can do as a programmer when choosing names is to use technical terms. This will save you and your readers time on explanations.

Use names of computer terms, design patterns, algorithms and so on. A programmer who is familiar with the Visitor design pattern, by reading the name AccountVisitor, already has an idea of what he or she will find inside that class.

USING PROBLEM DOMAIN NAMES

If there is no programming term for what you are doing, use the name of the problem that solves the part you are working on.

That way, if another colleague has to work with this code, they can ask someone who is familiar with it about the domain. And if not, at least that part of the code will have been narrowed down to a particular problem, taking some of the effort out of understanding it.

CONCLUSIONS

We have been able to review the most important points when choosing names in our code and we have also been able to see first-hand how simple changes can help the readability and maintenance of our code.

As we put these rules into practice, we will see that writing clean code is an exercise that requires discipline, perseverance and a critical spirit. But, it is worth it for all the benefits it offers when writing and maintaining an application.

Finally, I would like to make a special mention to a practice that I believe will benefit us as developers. This is nothing less than the golden rule of the American boy scouts: leave camp cleaner than you found it. That is, when you go to touch existing code, take a look around and if you see a name that can be improved, don’t hesitate to get on it.

José Álvarez – Software Developer at Itequia