Blog

4 Simple Rules to Write Clean Code

Publish Date 16 Apr 2020 Yifang YangYifang Yang

 

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.

 

Recent Posts:

Failure Analysis: Is it Important?
Publish Date 16 Apr 2020 Nathan SzantoYifang Yang

Yes.

Communication Through Design - Making Assembly Easier
Publish Date 16 Apr 2020 Garret HallmarkYifang Yang

After dozens of hours designing an assembly and weeks of waiting for parts to [..]

The Virtual Water Cooler

We have all experienced many changes to our daily lives over the past few months. [..]

Implementing OAuth2 Authorization in LabVIEW
Publish Date 16 Apr 2020 John AmstadtYifang Yang

  What is OAuth2?

Oil and Gas from a Sales Perspective

I have been fortunate enough to work in the oil and gas industry for over a year [..]

4 Simple Rules to Write Clean Code
Publish Date 16 Apr 2020 Yifang YangYifang Yang

  Computer code may seem structured and sterile. But, like any skill there is an art [..]

Popular Posts

Posts by Topic

See All Topic