I have produced code for over three decades, and it turns out that I am a slow learner. It’s taken me most all of those years to distill the indispensable principle of quality software: Readable code is often more important than correct code.

Code that is understood can be fixed, improved and extended by anyone. This is not always true of code that is merely correct.

It is far easier to make code understandable than to make sure it is perfectly correct. Making code readable for the unfortunate soul who needs to touch it is the very core of being maintainable. It’s the difference between being able to fix/modify/refactor vs deciding it needs to be rewritten (and the unfortunate expenditure of time, capital, opportunity cost and lost experience that rewriting code entails).

It’s important to remember that the ultimate goal is not code that contains function names filled with prepositional phrases, super descriptive variable names or long blocks of comments. When I propose a Culture of Readability, the idea is that any developer should be able to rapidly understand any length of code. Ideally, the overall point and structure should be obvious. Any subtleties or curious design decisions should be explained.

Time to Understanding Metric (TTU) is defined as “How quickly can you understand a segment of code?”

The tools at your disposal are many. Naming and comments are the primary vectors of conveyance. Overall software architecture can lead to better readability. The importance of documentations rises as the number of people who are looking at a given codebase increases. Humor can often be used as a neurological hack to make important points stick. As a last resort, create a Hat of Shame to bestow on those whose commits to master lower the average TTU.

Even though the discipline required to keep a high TTU has a cost, it ends up being a tremendous productivity multiplier over the long term. You will see the time it takes to debug, refactor and add new features shorten. Ultimately this means that you can spend more time improving your product and less time tracing existing code and swearing at those who have come before you.