The Importance of Readable Code

The notion of "clean code" has been around for almost as long as code itself, and many books have been written on the subject. This article is not an attempt to rehash well-established advice on best practices for clean code; rather, it is an overview of what it means for code to be readable, and what factors can affect this.

Syntax vs. Semantics

There are basically 2 fundamentally separate aspects to coding: syntax and semantics.

The syntax is everything that matters to a human: comments, variable names, whitespace, etc.

The semantics is everything that matters to a computer: what does the program do?

From the computer's point of view, the following two functions are identical:

/**
 * Clamps an integer between 2 limits.
 *
 * @param val Value to clamp.
 * @param min Minimum possible return value.
 * @param max Maximum possible return value.
 * @return val if it is already between the limits, otherwise min or max.
 */
public static int clamp(int val, int min, int max) {
    if (val < min) {
        return min;
    } else if (val > max) {
        return max;
    } else {
        return val;
    }
}

public static int func_1(int a, int b, int c) {
  return a < b ? b : (a > c ? c : a);
}

But let me ask you: which is easier to read?

Clearly, syntax has a significant impact on code readability, and code readability has a direct impact on code maintainability. Code that cannot be easily understood is code that cannot be easily maintained.

Syntactic Errors

As developers, we are trained to be attentive to detail. It is ingrained in us. Computers have zero tolerance for errors, and simple mistakes like a missing semi-colon can  break an entire program. While compilers and linting tools can help to lift to some of this burden, the fact remains that writing code requires careful, almost inistinctive, attention to detail.

Because of this, mistakes and inconsistencies in syntax can often stick out like a sore thumb. Let's consider another example:

/**
 * Clmps int betweeen  2 limits.
*
* @param val Value to clamp
* @param min Min possible return value.
* @param max
*     Maximum possible return value..
* @return val if its already between limits
*otherwise min/max
 */
public static int clamp( int val, int min, int max){
  if (val<min)
  { return min;
  } else if (val > max) {
          return max;
    }else {
  return val;
  }
}

This contains the exact same information as before, but the amount of time it takes to read is orders of magnitude greater. Why? Because the syntactic errors act as a distraction.

This is obviously an exaggerated example, but this same principle applies to any mistake, no matter how trivial.

Anything that distracts the reader from the semantics of the code is a hindrance to readability.

Tooling

Tools can - and should - be used where possible to help reduce these distractions.

I have already mentioned code linters, and these can be invaluable in identifying both semantic and syntactic errors.

Another kind of tool that is rapidly gaining popularity is auto-formatters such as Prettier. Global software consultancy ThoughtWorks recommended the adoption of automated and opinionated code formatters in 2019, saying:

Even if you don't agree 100% with the opinions of the various tools, the benefits of focusing on what your code does rather than how it looks is something most teams should be able to get behind.

Conclusion

Syntax matters.

It is good to be pedantic about small typographic errors when it comes to code, because eliminating these errors ultimately aids readability and places the focus squarely on the semantics.

Where possible, a tool should be used to assist with this, to save time for both the developer and reviewers.

Published 2020/10/08