<img height="1" width="1" src="https://www.facebook.com/tr?id=1101141206686180&amp;ev=PageView &amp;noscript=1">


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;



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.





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)




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:

Filtering Basics: Importance of Linear Phase
Publish Date 16 Apr 2020 Jason ThaiJason Thai

Linear phase and computation/memory complexity are important characteristics to [..]

Revisiting OAuth 2 in LabVIEW
Publish Date 16 Apr 2020 John AmstadtJohn Amstadt

Recap In my previous blog, we took a look at how to implement OAuth2 in LabVIEW. [..]

Engineering a Better 3D Print (Part 1)
Publish Date 16 Apr 2020 Michael MaloneyMichael Maloney

3D Printing and its widespread use has been a long time coming and seems to have [..]

NVCC – Intro to Utilizing GPU Power to Offload the CPU Part 3
Publish Date 16 Apr 2020 Jack BakerJack Baker

Assumptions: Machine has a Nvidia CUDA Core GPU (such as a GeForce) with installed [..]

How I Learn New Skills for Personal Growth
Publish Date 16 Apr 2020 Bryce UrestiBryce Uresti

Learning new skills can be quite the task especially when there's already so much [..]

Controlling the Supply Chain Dream
Publish Date 16 Apr 2020 Thomas MathewThomas Mathew

You are out with your friends, bird watching, and nothing could be more peaceful. [..]

Aligning Data in WAVE
Publish Date 16 Apr 2020 Rohama KhadijaRohama Khadija

When analyzing data from multiple sources, we often find that the time series data [..]