Best Practices for Readable Code

June 13th, 2015

If you are in the midst of writing a computer program, would you be able to remember exactly what your program does in a year from now? Would other programmers be able to look at your code and know what’s going on? If you don’t have a definite “yes” answer, then it might be time to upgrade your code documentation techniques! In this post, I will share a few “best practices” I’ve found useful for writing readable code.

Use Descriptive Identifiers

Firstly, programmers should use descriptive names for variables and functions. This will reduce the amount of comments your code will need. In other words, descriptive identifiers make code self-explanatory. Ideally, another programmer looking at your code should get the gist of what it’s trying to accomplish. Of course, comments are still crucial for well-documented code.

// Good! The code is fairly self-explanatory.
void insertNewItem(string product_name, int product_id)
{
  ...
}

// Bad! What are these things?
void a(int cv, int av)
{
  ...
}

Use a Consistent Commenting Format

It’s a good idea to use a consistent commenting style throughout your program. I personally like to use a style similar to JSDoc for commenting my code. JSDoc is actually an API that auto-generates comments for your JavaScript functions. JSDoc comments include “tags” for function parameters and return values.

/**
* Description of the function.
* @param {Data_Type} parameter_1 Parameter description
* @param {Data_Type} parameter_2 Parameter description
* ...
* @return {Data_Type} return_value Return value description
*/
function function_identifier(parameter_1, parameter_2, ...) {...}

As you can see, JSDoc is particularly useful for languages (e.g. JavaScript) where variables are weakly typed. A language like C++ is more self-descriptive, and therefore, requires less detailed documentation.

Here’s a JavaScript example that utilizes JSDoc style comments:

/**
* Compute the nth term of the Fibonacci sequence.
* Assume that the first term is 1 (i.e. fibonacci(0) = 1).
* @param {Integer} n: the index of the Fibonacci term, where n >= 0.
* @return {Integer} the nth Fibonacci number
*/
function fibonacci(var n) {
  if (n <= 0) return 1;
  return fibonacci(n - 2) + fibonacci(n - 1);
}

A note about function descriptions: To keep code easy to document and understand at a glance, it’s best to keep function descriptions as high-level as possible. In the example above, all we should see in the function description is what the function will accomplish, not how it works.

Avoid Redundant Comments

Someone once told me that comments are like toilet paper. You can never use too much. Well, I disagree! There was a time when I became overzealous with my comments. I used to comment lines of code that were fairly self-descriptive. Not only is this style of commenting tedious, it doesn’t really make the code more readable. Instead, it makes it more tedious to read.

Someone once told me that comments are like toilet paper. You can never use too much. Well, I disagree! There was a time when I became overzealous with my comments. I used to comment lines of code that were fairly self-descriptive. Not only is this style of commenting tedious, it doesn’t really make the code more readable. Instead, it makes it more tedious to read.

// Increment the product_count by one. 
// (No shit, Sherlock)!
product_count++;

Modularize as Much as Possible

If at all possible, avoid creating large “god functions” (a term my brilliant coworker coined one day). A function should accomplish one discrete task, not many. There are several reasons why modularization is a good idea:

  1. It’s more readable. (No one wants to sift through a gargantuan wall of text).
  2. It prevents redundancy. “Boilerplate code” (code that is commonly reused) can be packaged into discrete functions and called at various points in the program. This is better than copy-pasting the same old block of code multiple times.

Add a Meta Comment

Lastly, it’s a good idea to add a “meta” comment to the top of the file. This meta comment should give a succinct overview of the file and explain, at a high level, what the code does. At a minimum, this comment should include the filename, author(s), date last modified, and a brief description of what the code in the file accomplishes.

/*******************************************************
* product.cpp
* @author Karlina Beringer
* @date June 13, 2015
* @description This file implements the Product class.
* Products are sellable items in the store’s database.
********************************************************/

Categories: technology