The good, the bad, and the fast

Two of my most important lessons on code readability

Have I ever told you I used to be a book designer? The job title was DTP operator (that actually sounded so cool back then, but the pay was quite lousy). When you open a book and you start reading the text, that’s the work of a DTP operator. As a book designer, you don’t just pick fonts and line heights, and make things generally visually appealing. You have to understand the structure of the text, and ensure that the visual appearance conveys this structure to the reader. In fact, the visual appearance of the text is essentially a user interface for the reader to navigate the content. This eventually lead me to explore web development, and application development.

As someone whose job was, among other things, to create readable rendition of text, I was very conscious of the readability of the code I was writing. Most of the time I hated code formatters, and the piss-poor job most of them do. I still don’t understand why people think Prettier lives up to its name.

Recently, though, I have somewhat changed my mind. Not about Prettier, I still think it’s bad. I’ve changed my mind about the entire focus on readability that our industry appears to suffer from.

At some point, I had to address an issue in a somewhat large library in order to complete a task on one of the projects. It was an open-source library and I have only briefly studied the code when I was picking one, so I wasn’t too familiar with how it all worked.

As I dug into it to address the issue, it hurt my eyes. Mixed cases, mixed naming conventions, mixed versions of JavaScript, mixed paradigms. The code was all over the place. You could tell that many different people have worked on the code at different periods. The code base was quite old. Since it was either I fix the issue, or I wait possibly for weeks until the maintainer could do it, I decided to do it myself. I persisted and read the code over and over again to understand exactly what it does. Finally, I understood enough of the code to make the patch. I submitted it and it was merged with minor adjustments.

After a while I had to do another fix on the same library, this time on a different part of the code base. I noticed, though, that this time I did not have that much trouble finding the part I needed to fix, and the code overall made a lot more sense.

This taught me one important lesson: readability can be improved without making any changes to the code. All you need to do is become familiar with the code and learn to read it. I don’t mean learn to read a particular language. Learn to read the particular code base, get familiar with the authors’ habits, conventions (or lack thereof) — their style.

Recently, I was addressing a bug in one of my team’s projects. At the first glance, the code base was messy. The situation was quite a bit better than that open-source library as this was written by one person and within a short span of time and it wasn’t a lot of code. Still it was pretty tough on my eyes.

Mixed case, multiple ways of doing the same thing, huge functions with mixed concerns, unclear naming. Forgetting the first lesson, I started refactoring the code to make it easier to follow (for me). At first, I rewrote key parts of it in a sandbox to get familiar with the logic of the code — with what it was trying to achieve. When I was happy with the code in the sandbox, I copied it into the project and cleaned the rest up. After a day or two, 90% of the code was rewritten to my liking. It was clear(er), concise, used better naming, uniform formatting, clean separation of concerns. Then I ran the code. It was somewhat slow. It wasn’t bad, and I would probably be happy with it otherwise, but I recalled it being much faster before I messed with it.

I decided to figure out what the issue was. I instrumented both the new version and the original to measure performance. Sure enough, there was a 50% performance loss in the refactored version.

I kept the instrumentation, and started cleaning it up again. This time very cautiously. I was still able to clean some things up, move duplicate logic to a different place so that all branches would pass through it, and so on. Fixed the superficial stuff like naming and cases. However, every time I try to do something more radical, like factor out chunks of code into separate functions, the code would become slower.

In the end, I had to conclude that the basic structure of the code was optimal for the problem it was solving, even though it wasn’t as readable as I would like. My main take-away from this was that, from an engineering standpoint, learning how to read such code was far more worthwhile than attempting to make it more readable.

I still believe code is written so that humans can read it. Otherwise we’d just be writing machine code. However, one must never forget that the code is written for the machine to execute, and that that’s its primary purpose. Readability for human is just a side-effect of making it easier to write. The many principles of readability that we learn over the years have a tangible impact on performance, and not always for the better. Finally, the code base can become more readable just by becoming more familiar with it, and I think this is something we all hugely underestimate.