4 Simple Rules to Write Clean Code
Computer code may seem structured and sterile. But, like any skill there is an art to writing code that is clean and easy to read. Presented below is a list of 5 simple rules to follow which can help to make your code easy to read and understand.
1. Use clear and concise comments
Commenting your code is one of those things that everyone seems to understand and agree to being a good idea. But when you get code written by other people, it is more likely than not to have sporadic comments at best. Therefore, a good habit to get into is to add comments to your program as you are writing your code. This helps to make sure that comments are added where they are necessary and you don't forget to add an important comment somewhere critical. Furthermore, it is helpful to keep your comments concise and pithy. Avoid adding comments containing information that would be obvious to another engineer reading your code. For example, the code snippet below contains a useful comment.
while(uart_msg_rdy == 0) //Wait until a message is received from UART
Such a message outlines the intended function of the line of code and adds both clarity and removes any ambiguity for any engineer reading your code. The following code snippet however is unnecessary and generally considered frivolous.
X = 0; //Set variable X to 0
The comment does describe the function of the code in question, but it should be immediately obvious to a fellow programmer what the intention of the commented code is. In this way, this line of comment is probably not needed and for the sake of brevity probably best left out.
2. White space can be used to block your code
In many higher level languages, white space can be used to help delineate functions within your code. Compilers generally use white space to delimit tokens. Therefore, additional white space and newlines may not affect the actual function of your program. However, proper use of white space can help make code much more human readable. For example, consider the two loop examples below.
while(buff_index < buff_index_max) {data_buff[buff_index] = data_buff_empty; buff_index++;}
while(buff_index < buff_index_max)
{
data_buff[buff_index] = data_buff_empty;
buff_index++;
}
Functionally, from the perspective of a compiler, these two loops will perform identical functions. However, with proper spacing and use of new lines, the function of the second loop example is much better blocked out and therefore much more clear. An important note here is that Tab was not used to indent the lines on the second loop example. Instead, 5 space bars were used as tab does not indent identically on all machines. Therefore, it should be avoided.
3. Be as explicit as possible
A good way to help other people reading your code is to be as explicit as possible and avoid code that has obscure meanings. For example, consider the if statement below.
If(!rx_val)
{
err_cnt++;
}
The above code leaves some ambiguity as it is not immediately obvious what rx_val is supposed to be and what function it is serving. A better way to structure the above statement is to use the following format.
if(rx_val == 0)
{
err_cnt++;
}
In the above example, the function of the if statement is immediately obvious that rx_val is being compared to 0.
4. Be consistent
What I personally believe to be the most important rule on this list is to be as consistent as possible. This helps fellow engineers reading your code better understand your style which can allow them to learn how to better interpret your code in the future. To help ensure that your coding style is consistent, the use of a coding standard is important. A coding standard is a formalized document that outlines the types of rules like the ones above.
