Skip to main content

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.

Comments

Popular posts from this blog

Architecture of High Performance Computing Server at BIT Mesra

A High-Performance Computing (HPC) server was installed a few years back. It was a replacement for PARAM 10000, the supercomputer that is no longer available for use. Initially, the HPC was under the Department of Computer Science. The Department of Chemical Engineering and Biotechnology was the primary user of the HPC (mostly for simulation purposes), and so the administration decided to move it under the Central Instrumentation Facility (CIF). You need permission from the CIF to access the HPC. HPC is only available for research purposes, and you need to provide a good reason along with a proper recommendation from a professor to gain access to the HPC. The HPC is at least 20 times more powerful than the most powerful PC that anyone has on campus. Also, I recently checked the usage and realized that not even 10% of its power is being utilized. I hope this blog post will help you in understanding the core architecture of the HPC. Architecture The Architecture of High Performance Compu...

Setting up Machine Learning Environment on High Performance Computing Server

In the last article, I discussed the architecture of the HPC. If you have not read that article, I would recommend that you read it before proceeding with this one. Architecture of High-Performance Computing Server at BIT Mesra  The power of HPC can be utilized for its most important application in the field of computer science: Machine Learning. I am assuming that you already have obtained your SSH credentials to log on to the master node. Also, we will be setting up the environment in Python. Let's jump straight to the steps. How To? Step 1: Download and Install Anaconda on the Master Node Note that you are not the root user of the HPC. You are just a regular user, and therefore, administrative commands (such as sudo or su) will not work. Anaconda has made it much easier to install Python packages for non-root users, and we will be using Anaconda for setting up Python 3 and installing the required packages. Log in to the master node     > ssh be1005815@172.16.23.1 Go...