Writing highly readable code

Published in

The Startup

4 min readJul 29, 2015

We are always told that commenting our code is important. Without comments other developers will not be able to understand what we did and our future selves will recoil in horror when doing maintenance.

Readable code, however, is not only about comment text. More importantly it is about the style, structure and naming. If you get into the habit of writing easily readable code, you will actually find yourself writing less comments.

Let us take the following snippet and optimise it for readability.

This terse and confusing code calculates the age, in years, of each user record within an array. Their age is then added to the record in the array for later use.

So what can we do to make this code easy to understand?

Style

The first step is to correct the code style. Style may vary from project to project but should always include rules regarding indentation and spacing.

If you are starting a new project or are able to refactor your code to a predefined style it is recommended you use an agreed upon standard. For PHP the most well known standard is defined by PSR-1 and PSR-2.

This is what the code looks like after being indented and made to fit a maximum line length of 80 characters.

As you can see the code is immediately more readable. It also has the added benefit of being easier to edit.

Structure

Code structure includes everything from the directory tree in which the source is stored to the methodologies and libraries used. In the context of readability the important factors are abstraction, choice of control structures, data structures and use of temporary variables.

Refactoring for structure, in this case, means changing the for loop to a foreach loop and splitting the age calculation into a few steps. The value in the foreach loop has been set to assign by reference so that the array will be updated when the value is changed.

We can now easily see the separate steps involved in the age calculation and where the result is stored in the array. By using the foreach loop there is no longer a need to use an extra counter variable when accessing the user record.

Another possible change would be creating a function or method to perform the age calculation. Especially in a larger project where age needs to be calculated in multiple places.

Naming

You have undoubtedly heard the term “self documenting code”. By far the most important factor involved is the names chosen for variables and data structures.

Never be afraid of using longer names to improve readability. Good text editors and IDEs have completion so longer names won’t slow you down. Modern programming languages and databases support names of 50 characters or more. Coupled with the context of the name (table, namespace, class, etc) there is more than enough space to always have unabbreviated and meaningful names.

In our example the variables names and the keys used by the user records may be improved by using names which reflect their contents. Remember to apply the same thinking with all other naming including functions, classes, properties and methods.

The purpose of the code is even easier to follow now because we can see, at a glance, what is contained in each variable.

Comments

Comments should state in high level terms what the expected result of the code is. Never what the code is doing in low level terms. They should also document any side-effects that may not be obvious at first glance.

In this case only one comment is needed to specify what the foreach loop is doing. The comment for the users array has been removed because it is now easy to see what the array is for.

Go back and compare this with the initial code to see how much easier it is to understand.

If you find yourself writing code that is more like one of the earlier iterations, allow time to correct it. This investment will pay back many times over as your code base grows. Consider investing time in refactoring existing code too.

With a little practice and forethought, you will be writing highly readable code in no time.

Edit: Ryan Winchester has taken the code one step further and removed the need for comments altogether. Also see David Rosa’s response below for a different take on the styling.

Edit: Freek Van der Herten took Ryan Winchester’s code and refactored it some more.