Back to Basics – Readability

Arguably the most important skill in a programmer’s arsenal, yet possibly the one which he receives the least training in, is the ability to write readable code. This skill was barely touched on during my formal education, and I don’t see many blog posts about it, yet it is something which I take great pride in, and it is a quality which I admire more than any other in code which I read. It is the same with books, blog posts and articles I read. I really appreciate the ability of the author to take a complex subject, and present it in such a way that it can be understood by almost anyone (this is the reason why my favourite blog at present is waitbutwhy.com). Indeed, this is a quality which I strive for in my own blog posts, as well as my code.

The importance of readable code is largely known amongst programmers, but it is all too easy to overlook in our current industry climate. Such a strong emphasis is placed, for example, on making unit tests pass – the red light turns to green and we celebrate. However, readability is one aspect of your code which simply can’t be tested in any kind of automated way. We can specify inputs and outputs, and test functions for correctness and performance, but only a human can judge the readability of a piece of code, and even then of course there is no single right answer. When a book or article is written in a simple, clear and concise way, reviewers might describe it as “accessible”. That type of recognition is what you should be seeking from anyone who reads your code, it should be “accessible” to your fellow programmers.

Let’s remind ourselves then, why is readability even important?

The answer comes from the first rule of software development: The Only Constant in Software is Change.

You design, code, test and ship and you think you are done, but of course you are not. Your product will live on, there will be bugs to fix and new features to implement, and this work will often have to be done by other people. If your code isn’t readable, then others will have a hard time working on it, modifications will be haphazard and inconsistent, and over time your codebase will rot and a large technical debt will be accumulated. Furthermore, working on code which is difficult to read is just downright unpleasant and even be a cause for stress. So writing readable code is not only your professional duty, but also an act of kindness, or at the very least the decent thing to do.

Even if it is you who will be modifying your code in the future, don’t overestimate your ability to remember how everything works. If your project is at all complex, there is a good chance you won’t remember what you were thinking a few months ago, and you may wish that you had been kinder and more decent towards your future self.

So assuming you want to improve your ability to write readable code, how can you do this?

Firstly, you must have a good grasp of the English language. If English is not your first language, then this can be a big challenge, but the more fluent you are in English, the better you will be at naming your variables, methods, classes and modules. Getting these names right is not as easy as it sounds, and finding the right verb or noun often involves a quite subtle creative process. If English is your first language, then practice writing. Start a blog, write articles for CodeProject, or just start your own private journal. When you write, you are forced to think up words to express the abstract concepts in your mind, a very similar process to writing code.

Secondly, read good code. Code examples and tutorials from reputable sources (e.g. Microsoft or a famous blogger) would be a good place to start. Uncle Bob Martin has written a lot about readable code, including examples, in his book Clean Code. I remember reading this book for the first time many years ago, and how the importance of readable code really hit home. I still try to follow the Clean Code principles to this day. Another place to look for good code is popular open source projects, and consider reading code in a variety of languages.

Below is a list of 10 readability principles I follow when programming. I compiled this list retrospectively by thinking about how I like to code, and it is these principles which I am pleased to see in code written by others.

• Methods always start with a verb (e.g. GetProducts, UpdateSurname).
• Methods which return something always start with the prefix Get.
• Methods which begin with Update, Save, Create or Delete should not return anything except for rare circumstances.
• Classes and module names are always nouns. It is acceptable to choose a noun which stems from a verb (e.g. Controller, OrderProcessor).
• Comments should be avoided where possible, and only included when you can’t explain what is happening through your code.
• When choosing between alternative solutions, always choose the simplest and most readable. As an example, don’t automatically swap out a foreach loop for a Linq extension method just because ReSharper suggests you do so.
• Only choose the “optimal” implementation when you have identified a bottleneck and a need to optimize (no premature optimization).
• Don’t try to show how clever you are through your code, keep it simple!
• Don’t be afraid of long names if that’s what is needed to fully describe something.
• It is very important to keep methods as short as possible. Usually, extracting a method which you name well adds to readability. This principle also encapsulates other readability principles, such as avoiding excessive nesting.

Above all however, I would encourage you to remember the value of good naming, as this in my opinion is the cornerstone of readable code.

The post Back to Basics – Readability appeared first on The Proactive Programmer.