Writing readable code

Published on: 6th Jan 2025

Overview

Code readability does not have much to do with the language syntax. It is a habit that you need to keep up from day one.

Readable code

1. It is convenient in using if to check if a variable has value or not. For example, we can write code like below:

   let some_obj = null;
   
   if (some_obj) {
       console.log('the variable has some value');
   }
   else {
       console.log('the variable is null or undefined');
   }
   

   If some_obj has value, the true block will be executed. Otherwise, the false block will be executed. It is convenient and also confusing.

   A better way is to declare a function called has_some_value() to handle the checking.

   function has_some_value(v) {
       return !(typeof v == 'undefined' || v == null);
   }
   

   Then, replace the condition checking in if with has_some_value().

   let some_obj = null;
   
   if (has_some_value(some_obj)) {
       console.log('the variable has some value');
   }
   else {
       console.log('the variable is null or undefined');
   }
   

2. How many times have we glanced through a code block and overlooked the ! ("NOT") symbol...? Especially when we are rushing on some fixes, we overlook the ! symbol and causes another bug.

   let a = 1;
   let b = (a == 1);
   
   if (!b) {
       console.log('b is not "1"');
   }
   

   To make the code more readable, we need a new function:

   function is_false(v) {
       return (v === false);
   }
   

   After we have declared is_false(), we will have to rewrite the program in this way:

   let a = 1;
   let b = (a == 1);
   
   if (is_false(b)) {
       console.log('b is not "1"');
   }
   

   With this new is_false(), the program will be much more readable and it is easier to maintain even when you are rushing some fixes.

3. The convenience of || ("OR") operator comes with a price and confusion.

   For example, variable c gets either the value of a or b which depends on the runtime assignment.

   let a;
   let b = 1;
   let c = (a || b);
   console.log(c);
   

   The first reading on the above code looks easier to understand and intuitively say c will have the value of 1 since a is undefined.

   So, let's assign zero to the variable a. Guess what... should c take the value if a is zero? What is the user's requirement...?

   let a = 0;
   let b = 1;
   let c = (a || b);
   console.log(c);
   

   Here is another situation where it is confusing where a has false value. Should we assign this value to c..? It is difficult to answer when you are looking at the code.

   let a = false;
   let b = 1;
   let c = (a || b);
   console.log(c);
   

   || ("OR") operator is convenient but it is confusing. So, this is going to be time consuming by reading through the user requirement before you can answer the question.

   Let's say, the user is expecting any value that has been assigned to a and it will be used. In this case, we have to rewrite the code using has_some_value() (declared above).

   let a = 0;
   let b = 1;
   let c = (has_some_value(a) ? a : b);
   console.log(c);
   

Conclusion

Writing a program is not difficult but writing a readable and maintainable code requires more thought.

The example in this blog is only something we write on a daily basis. If you want to write a more readable code, you might want to ask yourself will you understand the code after you left it for twelve months while not touching it? If not, it is time to write some new function to make your program

Jump to #JAVASCRIPT blog

Author

Lau Hon Wan, software developer.