How to Write Clean Code as a Software Engineer
As the tech industry has been growing exponentially and software engineer has become a more prominent career, one attribute that fellow developers community tend to stress about is the quality of our codes. How do we write clean codes so other developers and fellow programmers can read and understand our codes. While writing quality codes do not have certain sets of standards, however there is a few rules and principles that we should follow to improve our coding ethics. Today we will take a look at some of the “rules” and write cleaner codes.
Before we begin, full disclaimer that I am by no means the “best” programmer, nor am I the most experienced tech person, in fact, I think there is no one can be the best programmer, one simply cannot learn everything and know everything about technologies. That being said, throughout my coding journey, I have found some tips and tricks that hopefully can provide some insights.
First tip of clean code might seem very obvious, that is to write the least amount of code. When we are trying to solve a problem, we often tend to take the shortest route, similar to that, when we are coding, we want to write the least amount of code to solve a problem. It is not only improving the time complexity that the code will run, it is also easier for human brains to read the codes when there isn’t too many loops and logics involved ( too many loops and if statements). Let us take a look at an example that shown in the following code snippet. In this function toAccounting(), we are simply turning a number to strings with accounting functions where if a number is negative, we put parentheses around it. First thing we notice is this function have an if and else if statement, and it isn’t necessarily needed. if n < 0, we would return that number with parentheses, and for any other cases, which would be when n is equal or greater than 0, we would simply return the number. Therefore, we don’t need else if statement in this case, we can simply use else statement to reduce the amount of code we write.
And yes there are so many other mistakes or should we say “dirty codes” for the code snippet above, this brings to our tip number 2. We are looking at these terrible variables and function naming! Yes, it is readable to a certain degree, but it would take us a much longer time to read and process in our mind regarding what the function does and what this variable means, and we should aim to name our variables and functions as specific as possible, as detailed as possible, this way there is less confusion involved. The code snippet shown below give us a much better understanding of how to write the same function with cleaner codes. By naming our function numberToAccountingString, we understand what it means and what the function actually wants to do. By naming our variable number we automatically knows what it is and how to deal with it.
One side note when it comes to variable naming, try to avoid negation! The reason being is that when we negate the variable using Boolean, and it will turn into double negations and it would be a nightmare for everyone to read and interpret at times! We cannot tell right the way from this variable naming, and it would take us a few seconds (or few minutes lol) to understand isNotBlocked = false, meaning that it is blocked! and if !isNotBlocked means not isNotBlocked, which means it is blocked?!? We can tell it can get complicated very quickly, why not try the following code instead? const isBlocked = true; if(isBlocked) { //Do something }; Coding can be expressed this way and it would take fellow developers so much easier to understand it!
When it comes to naming our variables, sometimes it is more than just naming the variable itself. We can extract a piece of complex code logic into a self-explanatory named variable so we can understand the logic and its purpose much quicker. Let us take a look at the following code snippet, obviously we cannot tell right the way what this piece of code is returning, and all of the conditional statements that it has, what is it trying to do. What we can tell is that it is trying to render a button to cancel meeting, but how do we understand what are the pre-requisites to render this cancel meeting button?
By simply extract pieces of codes out to different variables, we can hopefully capture right the way what are the requirements to render this cancel meeting button! And from the following improved clean codes, we can tell that the first variable is meetingHasStarted, the second variable is defined to see if the person has created this meeting, and the third variable determines whether the person hasCancelPermission to this meeting. Once all the pre-requisites are there and defined with good variable naming, we can easily determine the logic when the cancel meeting button should be rendered.
So what happens when we cannot just explain our codes and logics with a self-explanatory naming convention? This is the third tip when it comes to writing clean code, write comments and code documentations. But didn’t we say earlier that we should be writing least amount of codes when it comes to writing clean code? Yes, but there is always exceptions to a “rule”, especially when it’s not set in stone defined as a golden rule to any standards. Comments and code documentation is very important in terms of explaining your thought process and logics, because when we are working as a software engineer, we are bound to work in a team with other developers, which means we need to communicate with each other and understand the different styles of writing codes are. The simplest way to express that is to write a comment to explain what we are trying to do with that piece of code. And the following code snippet can be a great example to show why comments and code documentation is very important. We understand from reading the code that this function is trying to manipulate an element on DOM and change its text, its color, but without the comment, mostly likely we might not understand why the developer wants to set the element.style.display = “none”; then set it back to empty string after manipulation? But reading through the comment, we can quickly understands that the developer wants to display none to minimize the number of renderings that happens when we set the text and the color of this element.
There are so many more tips and tricks when it comes to writing clean codes. And there is not a set of standards to it, but we are in this coding journey all together, and hopefully we can learn from each other when it comes to writing cleaner codes and help to improve our fellow developers community! Feel free to reach out to me via LinkedIn and I am happy to connect and chat with y’all! Thanks for reading and have a great rest of the day!
