Making Good Software

A blog by Alberto G (Alberto Gutierrez)

Written by Alberto Gutierrez

June 22nd, 2009 at 5:45 pm

How to write readable code? 5 Tips to improve your code readability.

with 2 comments

As explained in the article the pyramid of software quality, readability is one of the most important characteristics of good code. These are a few tips that may help you to produce it.

1.- Use a top down approach (TDD).

Using a top down approach is similar to TDD you start with the highest level logic: the validation of what your code has to perform (The unit test), and then you add layers of abstraction, which as you keep coding become more separated from the domain problem and more related with implementation details. This approach helps to produce more readable code because:

  1. Producing the unit tests will give you a general idea about how readable is your code. Readable unit tests generally mean readable code.
  2. Separating the implementation details and the domain logic makes them easy to understand.

2.- Make your design match your domain (LRG and DDD).

In the excellent book applying UML and patterns, Craig Larman introduces the concept of Low Representational Gap (LRG). The representational gap is how different is the domain logic of an application from its design, having a low representational gap means that the design has very few differences with the domain logic it represents. LRG and Domain Driven Design DDD are much related concepts as they both focus on designing a domain model that matches the real model.

An application that has a LRG will be much easier to read because the actual domain logic will match the implementation domain logic.

3.- Use abstractions only when necessary (YAGNI and KISS).

Sometimes is tempting to make everything too much flexible. As software developers we always have to have in mind these two principles: You Are Not Going to Need It (YAGNI) and Keep It Short and Simple (KISS), remember: Code is not better because it has abstraction layers that may be useful in the future, they are going to make your code harder to read, just use abstraction layers when you need them now, not just in case they are necessary in the future.

4.- Use good names.

Using good names in your code is critical, it will make a difference between a code which will be read as plain English and a code where you will be shouting WTF?!! every two lines.

In this article: tips to write variable names, there are a few tips that can actually be applied to name any named element not only variables.

5.- The 5 minutes explanation test.

Apart from using the previous 4 tips and some other guidelines you may think appropriate to create readable code, I like to pass the 5 minutes explanation test to my code to know how readable it is.

  1. Grab a fellow programmer who spares some time to review your code
  2. Walk him through your code, just a high level introduction.
  3. Ask him if he understood your code.

After following these steps you can evaluate how readable your code is based on how much it took you to explain it. I call it the 5 minutes explanation test because as a rule of thumb if it takes more than 5 minutes for the other programmer to have a high level idea of the design, assume that the code is not readable.