Comments in a Code v/s Code Readability

 Recently I have 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 usually checked in by my team to Google's codebase. I am an exhaustive code reviewer. I only accept code with the highest standards and best practices followed (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 adding this small write-up to explain the reason.

I really believe that writing code is very similar to writing a very simple story without any twist. 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 which are too obvious. Similarly, a piece of code must narrate a story to the reader. The code should be so clear that a person reading the code must be able to guess the next lines (and possibly even the entire file) without even reading the entire code line-by-line. It should create an immediate interest in the minds of the readers.

In such a case, 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 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. The code is, in fact, unreadable. The readability can be improved by introducing another character (variable) and renaming some existing characters.

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

Here are the important readability improvements:

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

• The code clearly tells the 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 guess the internal code details.

• Some argue that declaring a variable slows down code execution. This might be true for interpreted languages. For compiled languages, the compiler always optimizes the code automatically for such cases. Anyhow, if you are concerned about speed, why would you use an interpreted language. Moreover, code execution speed is never an excuse for readability. Most of the readability sins are performed in the name of optimization only.

I hope I have made kept my explanation simple and clear. I understand that this is very subjective. Different people might have different opinions on readability. That is why I always say, finding solutions to algorithmic problems might be science but code implementation is always an art - an art of expression.