You have always heard that it is important to write code that is more “readable”. But what exactly makes the code more readable? There is no absolute answer to what is readable code. It varies depending on the developers and even what you consider is readable code. Readable code to one developer might look like any other code (even badly written code).

My goal for this post is to talk about some hidden or not so obvious factors that contribute to code readability that is rarely taken into account. This might help explain why some developers describe a piece of code as “readable”, while other developers do not see it as “readable.”

What Is Readable Code?

The simplest way to describe readable code is that it is code that makes sense when you read it. It is easy to understand the intention of the code. In addition, the code is easy to follow. The code is best described as clear and concise.

The Standard Answer to Readable Code

Regardless of the programming language, there are common factors that contribute to the readability of the code. They are:

• Good variable, method, and class names
• Variables, methods, and classes have a single purpose
• Consistent naming style for variables, methods, and classes
• Limited amount of nested level code

If you are interested in learning more about “good code” and readable code, Code Complete by Steve McConnell or Clean Code by Robert Martin is great resources.

The Audience Matters

You are probably wondering, “What do you mean by the audience?” “The audience of my code is obviously myself and other developers.” That is true, but when you look at developers as a single group, you are inferring that they are all able to understand your code. In reality, that is unlikely to be the case, because not every developer is skilled in the same area and have the same experience.

You can take a sample of your best well written and highly readable code and give it to a beginner developer. They most likely will not find the code more readable than some badly written ones. Having descriptive variable names, well-named methods with concise purpose, and structure to clearly group functionalities together does not make it any easier to read for a beginner. Trust me, I was once a beginner developer, who felt that “readable” code was harder to follow and understand because there are so many methods and long variable names.

How Beginners and Experienced Coders Read Code

When reading code, an experienced developer focuses on the actual concept or intent of the code. Whereas, a beginner developer will focus on the syntax and variable types opposed to the intent of the code.

To a beginner, long and descriptive variable names are not helpful or readable because they hide the type of each variable and personifies them to be something more. They would prefer the variable be called X because it is less confusing to remember than the long variable name is of type something.

For an experienced developer, they do not care about variable types. Instead, they want to know what the variable represents in the logical context of the code.

What Can We Do?

You are probably familiar with the idea that you cannot please everyone. Therefore, what you can do to write code that is more readable is to find out who your audience will be. If your audience is experienced developers, then you can aim to be more expressive and less concern with the vocabulary and syntax of the programming language. However, if less experienced developers will be working with you and your code then you might want to reduce the expressiveness in order to make it easier to follow for them.

Here is a simple example of code that does a very simple task. In one case, it uses the conditional operator and another case uses an if-else statement. Also, assume that an Action structure is defined elsewhere in the code.

Action next_action = kitty_is_hungry ? Action.Feed : Action.Play;

Action next_action = Action.none;
if (kitty_is_hungry) {
	next_action = Action.Feed;
} else {
	next_action = Action.Play;
}

When I was starting out with programming, I believed the second way was better, but now I find myself writing the first way most of the time. Does that mean one way is better than the other? The answer is that it depends. For a beginner, the conditional operator might be confusing, which requires them to focus on the vocabulary instead of the intent. For an experienced developer, the if-else equivalent will seem drawn out and a waste of space.

It is important to note that from the example it points out the importance of the audience’s vocabulary in the programming language. The larger vocabulary your audience has, the more expressive your code can be. Another way to look at it is that you have more freedom to write your code.

I hope you found this post helpful. If you found this post helpful, share it with others so they can benefit too.

Did you ever find yourself in a situation where everyone is praising how readable and good a piece of code is, while you look at it confused and lost? Have you been told that your best-written and readable code sucks by beginners? Maybe this post helps shed some light as to why that is the case.

To stay in touch, follow me on Twitter, leave a comment, or send me an email at steven@brightdevelopers.com.