In words of an unnamed classic – life would be much easier, if we could have a look at the source code. Per this interesting calculation, there might be more lines of code written now, than stars in the Milky Way galaxy. Five times more. Possibly more.
I do not believe there was a way invented yet for engineers to learn about a system without looking at the code. For an average company (say between 5-10 years on the market), you will most likely meet at least millions of lines of code you’d need to read to understand everything. And ten of thousands being added each month.
Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code. ā¦[Therefore,] making it easy to read makes it easier to write.
Robert C. Martin, Clean Code: A Handbook of Agile Software Craftsmanship
While it might be impossible to understand everything, it is very important to make reading code easier. To that effect, I have been looking at scientific, empirical evidence, rather than just assumptions in books by classics. Even, if they are right to a degree in some of their statements :).
There is a lot of evidence that code readability (also defined as code, where a programmer could understand the context as well as what a specific routine might be doing) plays a significant role in software quality. Through that most researchers conclude a stance, that understanding before writing is correlated with the eventual satisfaction of the end user; not only satisfaction of the developers writing new code.
One particular study caught my attention, while reading through the material. Specifically this one: Impact of Programming Features on Code Readability, Texas A&M University-San Antonio by Y. Tashtoush, Z. Odat, Izzat M. Alsmadi, M. Yatim.
What caught my attention here is focus on having a tool that is able to predict software readability. The output of the tool is then reviewed by a larger number of experienced software engineers in mixed backgrounds. The results are further used to adjust the outputs of the automation.
To allow for use of automation, the very abstract concept of readability is broken down to quantified features. These are (for example, as the study lists 22 individual features) characteristics like: meaningful names, comments, but also nested if-else loop number or use of recursive methods.
What is highlighted in the conclusions, and not a surprise, is that adding meaningful names, comments and keeping code consistent (including styles and notations) are the key factors positively contributing to readability. Not surprisingly recursive methods, nested loops and arithmetic formulas are on the opposite side of the spectrum, negatively contributing to readability.
The surprise is hidden in the section of factor not having a strong negative or positive impact. These include long if-else statements, length of a method (short scope), overrides in OOP, long switch statements. This is strangely contradicting some classics.
Now that I think of it myself, it makes sense. I have seen long methods in my life, that are simple to understand. I was never a fan of algorithms, so not surprised they might be less readable (arithmetic formulas). You need to understand computing algorithms to be able to read their code.
I am not saying one study should sway everyone into contradicting, the so called clean-code-fascism. Although before you will start complaining about long methods or constructs used by others, having that short scope bias, it is worth to check if you can understand the logic first. In the end it is not the style, but readability that counts. And by readability, whether you were able to understand code.
And whether you like it or not, using long and descriptive variable, method and class names will mean your program takes up more space. There are industries where it does not matter, but there are those where it does. The devil is always in the detail.
To wrap up what we have learned today:
- Readability of your code is a factor that may contribute to the eventual success of your product
- It is worth to start thinking on having code readability metrics (even if it’s a simple check of having a readme and a style formatter); even if to just understand how big of a problem it might be
- If the above fails, number of wtf per minute still applies and should be easy to measure just by talking to your software engineers
- Some factors we might very passionately fight for (like short method scope) might be playing less of role in the eventual readability than one would thought
- There are other factors beyond readability when deciding on code structure
- Just following clean-code-fascism will not help you to be more successful
- The study I used was a c# program analysing java code, so it might be biased š
Gustaw Fit 