Like writers of stories or poems who worry about the spelling and structure of their words, developers must worry about every piece of code we write. At any moment, someone else could work with our code and it needs to be understood and readable as if it were a newspaper. In reality, our code is our signature and legacy for a project, so for the benefit of all, it is important that we constantly practice and dedicate ourselves to learning how to write clean code.
Learning to write clean code is not easy, and not something that can be mastered overnight. There is no universal guide that we can all use to code. But there is helpful advice and best practices from experienced developers for reference. I recently began to learn about the best practices of writing clean code and below I share some useful tips to get you on your way.
Call Me By My Name — Use Meaningful Names
Assigning meaningful names to classes, methods, and variables is a good way to start cleaning up your code. When you create a method or function, and a series of instructions, if you really analyze it, you often find the name you need for the method. For example, instead of naming a method johnCena (), or grc (), to generate a report on a customer’s purchases, I can assure you no one will know what it means in either instance or what it does. Yet, if you call the method, generateReportForClient (), it’s a lot clearer and by seeing the name you will know what action the method performs.
This also applies to classes and variables. It’s important to avoid shortening names. A long and understandable name is preferable to a short one with ambiguities. When you take the time to define a correct name, I can assure you that in the future both you and whoever reads it will appreciate it.
Do Not Repeat Yourself
Some Integrated Development Environments (IDE)s can help you make sure you don’t repeat yourself by duplicating code. For example, Intellij IDEA highlights a yellow warning signal when it detects repeated code. This means that the code can improve, and you can eliminate the repeated code using methods or classes. So, when developing you must be very aware and realize that when you see a code that does the same to the development, you can refactor it using a method. It also helps to keep the number of lines in classes smaller. Eliminating duplicity is key to writing clean and readable code.
One Worker, One Task
Functions and methods allow you to encapsulate the actions that the objects perform. It is important to keep them organized and make sure they only do a single task. You cannot create a method and call it “save (User user)”, if the code is designed to eliminate two objects, sum 2 + 2 and generate 5 reports and then save the User object. You also should make sure you don’t call the function saveAndDeleteAndGenerateReport (User user); as a solution. It’s important to be clear that the function should only save the user object.
The number of parameters is also important. Having more than two is an indication that the method does more than one thing, so it is very likely that you can split what you want to do into several methods.
Avoid Unnecessary Comments
Let’s agree to avoid using comments as a way to explain unreadable code. If you need to comment on a code, it is very likely that you will have to write the code again. Often, you understand what the code does, but you are worried that someone else cannot understand it, so you resort to leaving a comment. If that’s the case, you need to consider rewriting the code since it must be understood in the first instance. The code should speak for itself.
It’s important to remember that if you apply the previous tips, you won’t have to leave a comment about what a certain function or variable does since the name will give you an idea about the action to be performed. When you write clean code, you can use comments to provide more information about business rules that will be important for a new developer to understand.
Implement Team Coding Standards
All programmers have preferences about the format of a code. A typical example is in the location of the braces in the methods or classes. Some prefer them next to the signature while others prefer it below. When working as part of a team, preferences must be set aside and a common agreement reached so that the entire project is written in the same format. If it is decided that two spaces will be left between functions, it is your duty to write and correct it each time you see a code that does not comply with the team’s coding standards.
What’s next?
These tips are a summary of what I have learned in several months of study. To get started, I highly recommend a book called Clean Code: A Handbook of Agile Software Craftsmanship written by Robert C. Martin. The author goes into more detail with several of the terms that I mention here and other more advanced ones that might interest you. Unfortunately there’s no short-cut to writing clean code, but with a lot of practice you will be applying these concepts in no time.
