Comments in a Code v/s Code Readability

Recently, I earned Readability (a Google certification for language expertise) in Java and JavaScript. Over the past few months, I have been a Readability reviewer for most of the code that is typically checked in by my team to Google's codebase. I am an exhaustive code reviewer. I only accept code that adheres to the highest standards and best practices. (Okay, enough of blowing my own trumpet!)

One of the most popular questions that I usually receive is, "Shall I add a comment here to make things clear?" Most of the time, my answer is a clear "No!" I am writing this small write-up to explain the reason.

I truly believe that writing code is very similar to writing a very simple story without any twists. The variables are the characters. Expressions provide a characteristic feature to a character. Each function narrates a conversation between variables, much like an act in a play. While reading a novel, the reader's mind tries to guess what could be coming next. The reader also tries to skip the lines/phrases that are too obvious. Similarly, a piece of code should tell a story to the reader. The code should be so clear that a person reading the code should be able to anticipate the next lines (and possibly even the entire file) without even reading the entire code line by line. It should create an immediate sense of interest in the minds of the readers.

In such cases, comments are unnecessary clarifications that are added to the code. While code documentation helps in understanding the overall result of the code execution at a certain level of abstraction, code-level comments are a clear sign that the code is unreadable and that they have been added to increase code clarity. For example, take a look at the following piece of code:

function computeVolume(r, h):
    # Calculate the base area and then multiply by height.
    return (PI * r * r) * h;

The comment in the code above is completely unnecessary. In fact, the code itself is unreadable. The readability can be improved by introducing another variable and renaming some existing ones.

function computeCylinderVolume(radius, height):
    baseArea = PI * radius * radius;
    return baseArea * height;

Here are the important readability improvements:

• The code no longer disrupts the flow of the reader. Switching between reading logic and reading English statements slows down code reading.

• The code clearly tells a story. The function signature, combined with proper variable naming, no longer requires documentation. The code is implicit. Just by reading the name of the function, the reader can anticipate the internal code details.

• Some argue that declaring a variable slows down code execution. This might be true for interpreted languages. However, for compiled languages, the compiler always optimizes the code automatically for such cases. In any case, if you are concerned about speed, why would you use an interpreted language? Moreover, code execution speed should never be an excuse for sacrificing readability. Most readability sins are committed in the name of optimization.

I hope I have kept my explanation simple and clear. I understand that this is a subjective topic. Different people might have different opinions on readability. That is why I always say, finding solutions to algorithmic problems might be a science, but coding is always an art.