Clean Code: Aesthetics of Coding
As a programmer, we would usually want for our program to just work. We simply don’t care to much on our code readability or usability. One such example is to use very simple variable names such as x or temp. This may be good for that programmer because he/she may code very fast. But for other programmers trying to understand that program, it will be so hard and confusing! One solution of this problem is to write clean codes.
What is clean code?
Clean codes are simply put codes that can be read and enhanced by a developer other than its original author. One may achieve this by making the logic of the code straightforward and simple. In order to make clean code there are several characteristics that a programmers should try and follow.
Characteristics of clean code
- Code should be elegant which means that it should be pleasing to read. It should make you smile the way something that makes you happy would.
- Code should be readable which simply means that anyone can read codes easily like a well-written prose.
- Code should be simple in which means that each function, each class, and each module exposes a single-minded attitude. This is also known as the single responsibility principle (SRP) which simply means that it should do one thing.
- Code should be testable which means it should run all tests.
Meaningful Names
One of the common and effective ways to achieve clean code is by writing meaningful names. Choosing good names may take time but as a result it will make your code better and cleaner. One of the best benefits is that your code will be easy to read by other developers and yourself in the future. One way to look at good naming is that if a name requires a comment, then the name does not reveal its intent which we should avoid.
An example would be to write something like:
int d; //elapsed time in daysRather than doing that, it would be much better if we write:
int elapsedTimeInDays;Class Names
When naming a class, it is best to name classes with a noun or noun phrase names like Account, Customer, and AddressParser. But avoid names such as Accessors, Mutators, or Data. Class names should not be a verb.
Method Names
On the other side, methods should have verb or verb phrase names. Examples of naming methods would be createUser, deletePage, or save. Method naming should also describe the functionality of that method so that it will be easy to understand and to use.
Pick one word per concept
One concept in your whole application should have the same name. One simple example is to have both fetch and retrieve in different classes which essentially means the same. This is bad because it will confuse programmers as they will not remember which name goes with which class. By picking one word per abstract concept you will make it quite simple on reading codes and during further development of your codes as well. This is due to the fact that abstract concepts are named the same which will be easily remembered.
Functions and Comments
There are several other guidelines on writing clean code for functions and comments. One of the basic rules as mentioned before is that a function should do one thing which follows the single responsibility principle.
Functions should have less than 3 arguments. This may seem astonishing but it is actually quite useful as developers would only need to worry about zero to two arguments on a single function. If a function needs more than two arguments, it is most likely that some of those arguments may be wrapped to a class. Reducing arguments by creating objects may seem like cheating but it is actually not.
When you write functions you should definitely avoid repeating yourself as duplication creates a huge problem for software development. One of the main problems is that suppose you want to add a condition on a function, but you have another function that is a duplication of that function. Thus you will need to add that condition twice on both functions which is just actually redundant. The principle of not repeating yourself is also known as DRY or Don’t Repeat Yourself.
Lastly are about comments. Comments do not make up for bad code. Ideally, comments are not required at all. By choosing the correct names, we would prevent commenting our code which is why naming is quite important. Legal comments such as copyrights or licenses and certain docstrings are not considered here.
Using Linter
At the beginning, wanting to code cleanly will be quite hard and confusing. It will take time to get use to. But there are tools that may help you to do clean code! One of the tools available are called Linters. Linters are basically tools that analyzes source code to flag progamming errors, bugs, stylistic errors, and suspicious constructs. Each programming have their own variety of linters available. For example in Python it is called PyLint while on Javascript one of the lint tools available is called ESLint. An example of using PyLint can be seen on the image below.
I personally recommend using linters as it will make your development team have more insights and also getting used to clean code. This will be most beneficial on the long term as your entire development team will be able to understand each others codes quite easily. Furthermore, when a new developer joins your team, they will easily understand existing programs due to clean code.
Clean Code in My Team’s Project
In my team’s project for SmartCRM we have implemented clean code to the best of our abilities. Reasons for this is as mentioned before using clean code may ease the use during future development or when our code has to be reread by our client or a future developmen team. Another reason is to make our code easy and simple to understand. During the course of our development, I have focused mainly on the backend of our app. Thus, the examples I will discuss are codes from the backend using Python as the programming language.
Naming
In Python, as you may have probably know, the naming of variables, functions, and classes use the term known as snake case. The use of snake case can be identified by seeing the use of the “_” (underline) character. My team has followed the use of snake case on our python programs. It is quite simple and thus easier to see the codes afterwards. Here are a few examples.
As you can see from several examples above, the use of snake case for the naming of variable and functions makes our python programs simple, readable, and elegant. The function names also satisfies the single responsibility principle as mentioned before. It can be seen that for constant names, we use all caps for the name. This is to distinguish which variables are constants and which ones are local variables to that function.
Terms Used
The use of terms is very important in a software. Terms should be constant and used the same throughout one software as discussed before. In my team’s project, we have selected several terms to be used.
- Regist or registration which is the flow of the registration process.
- Identify or identification which is the flow of the identification process.
- Payload which is the term used as the json formats to be sent between frontend and backend or between backend and the dummy API.
- Passcode which is the term used to describe the selected image as passcode to be sent.
- Validator which is the validation class to be called when validating a payload
- Processor which is the image processor class to be called when we want to process images sent from the frontend API.
As can be seen on the image above, the use of terms often makes it quite easier to create codes. It can be seen that the terms “regist”, “payload”, “processor”, “passcode”, and “validator” are used very often. This is because, our team has define the definition of each of these terms. Thus, naming variables using these terms will, in a way, define these names by itself. This is why for me and my team using terms is very important as it can play a major role during the development process and even in the future.
Comments
As for comments, all the comments we have made (on the backend app) are pure docstrings required for each class and functions. Docstrings are put on every function, class, and the module itself. You may ask why are docstrings important. It is actually decided in my development team that rather than using a lot of comments we are just using docstrings to define what the class or function are doing NOT how they do them. The reason why this is done is because some complex functions or classes may be hard to understand or takes time to understand thus why docstrings would help a lot.
Another reason why we decided to allow docstrings is that because on our development (using python as seen above) we are using the PyLint software on linting. As described above lint tools are quite important and PyLint demands that every class and functions have their own docstrings. Results of the PyLint run on my codes can be seen here.
This proves that we have successfully implemented clean code on our project.
The Cleaner The Better
As a conclusion, I personally think that clean code is important and very beneficial on software development. The use of common terms for example is important and makes development quite easy. Terms can also be used to explain cases to users or clients. The use of identical naming characteristics for variables and functions such as snake case or using caps for a constant will also make your code very easy to read and thus makes your code cleaner. Using minimal but menaningful comments will also make your code simple and easy to use in the future.
Clean code enables your team to be able to understand each others code easily and efficiently. In my experience, using linting softwares will help the team quite easily as well. The combinations of using clean code and linting software will almost guarantee your team’s code to be clean. Thus, your code will be much more valuable and easy to understand in the future.
When you are looking to make your code more aesthetic, clean code is your answer. — Raihansyah Andrian
