The Importance Of Readable Code

Photo: John Schnobrich - Unsplash

Something I am passionate about is readable code. I mean really passionate, opinionated if you will, about it. This does not mean following some code formatting recommendations. Nor linter’s or tools such as Resharper. (Although I would say use these tools from the outset of your project to support your efforts). I am talking about how you structure your code and what names you apply. I am also talking about consistency and I am definitely talking about removing obscurity.

Why am I so passionate?

Because you will read significantly more code in your career than you will write.

It’s a skill that often comes with experience, both career and technological. Most junior developers aren’t told to learn to read code. They work hard to learn the principles of programming and a given language. They are encouraged to play with the code and what they have learnt. Simple examples such as a Hello World application or a Todo list are shown. Most developers learn online these days and will copy, paste and run the code. Very few times in tutorials or courses do they say “Go to GitHub and read the code in repo x,y and z”. Most example code is exactly that, an example. It’s not the real world. As I shared on Twitter the other day, I am old enough to remember learning to code form books. I could not copy and paste the examples and just run them. I had to type them out. I would read endless examples to develop the answer to my problem.

When we learn English (or whatever your language is) you are taught to read and write. By doing so you enforce both actions and the impact one has on the other. It enforces what has been learnt and exposes us to more advanced syntax and different styles. This is the same for code. If you are learning a language, reading other developer’s code will benefit how you write code. You might read some bad code but you will also identify good code in your languages ecosystem. Just like reading books help to broaden and enhance your knowledge so will reading code.

The harder part of reading code is that it is not as structured as most spoken languages. This is ironic as most languages have very few keywords in their syntax. So they should be easy to read. The difference with programming languages is that they have limited rules around the syntax. This leads to infinite ways in which to use them.

This week I worked on fixing a page in our application that provides a forecast calculator. The page was an external, anonymous, page. Pure Html with posts to a server controller. It took about 4 hours reading through this small code base to work out what was going on. That was the time it took to unravel the code to understand what the problems where and how the feature worked. The reason was the way it was written made reading it extremely hard. Poor composition, inconsistent naming conventions and out of date comments all pilled up.

Take the following snippet of JavaScript

function isValidDate(s, prevYears, futureYears) {
    var d = getDateFromString(s);
    
    var bits = s.split('/');
    var validDate = d && (d.getMonth() + 1) == bits[1] && d.getDate() == Number(bits[0]);
    
    // rest of function

}

Compared with the following with a few minor changes

function isAValidDate(dateString, previousYears, futureYears) {
    var dateToValidate = createDateFrom(dateString);

    var dateElements = dateString.split('/');
    var isValidDate = dateToValidate && (dateToValidate.getMonth() + 1) == bits[1] && dateToValidate.getDate() == Number(bits[0]);

    // rest of function

}

What do you find easier to read? I accept that there are more characters but I will ignore comments on that. Today’s editors all come with Syntax highlighting, templating and autocomplete. That is no longer a real reason for variables names d.

So over the next couple of posts, I am going share how I write code to be readable for myself and others. Most of the tips are already available on the internet but I have a few ideas I find quite powerful. I will also address the cost to a project when you allow unreadable code to persist.

If you have any thoughts around code readability or topics that could be covered in the next couple of posts then please contact me via twitter or email.