Tidy Code and Architecture

We spend significantly more time reading existing code than changing or adding code, and we also spend significantly more time finding bugs than fixing them.

In that sense, it is important to consider extraneous cognitive load, as acquiring understanding by reading and debugging code is apparently the most time-consuming. Reducing the time needed to gain understanding makes us more effective. One might say that reading is the highest contributor to increased overall cognitive load within a software development environment.

By actively applying well-known design patterns and principles (such as SOLID, DRY and YAGNI), one can make a codebase tidier—in other words, "readable"—for all, not only experts. The design principles are like the maps we use to go from point A to point B in our cars; they guide us to rapidly navigate codebases without going into every single detail. This way, we can rapidly grasp where we must apply changes, drastically lowering extraneous cognitive load, especially when compared to building legacy codebases without well-known design principles.

We observe that the incentive to write easy-to-read code for others is low when the code is not actually read by other people. A direct causal relationship exists between the number of people who will read and maintain the code and its readability. If many others need to read the code, they will, out of frustration of being cognitively overloaded, either demand improvement in readability or improve it themselves. And the same is true the other way around: code maintained by one or just a few people is often not even readable to them after a long period.

Having said that, there are also engineers who improve readability to a certain level because they must maintain it themselves or simply because it is a good practice, even if nobody else will read their code. There is, though, a significant difference in readability if a person needs to read the code themselves compared to when others need to read the code.

We observe that product development groups often limit the number of people who read and maintain the code—this is a simple and seemingly obvious solution to the immediate cognitive load introduced by hard-to-read code. The consequence is not only bad software quality due to low readability but (ironically) higher cognitive load required to maintain it when, later, maintainers leave the company or are promoted. For many product development groups, it seems impossible to, at the very least, maintain certain readability over a longer period (years) with a growing codebase. It has become normal for code to become worse over time and to maintain a long list of bugs. Until one encourages many people to read and change the code of others, quality doesn’t degrade; it even improves over a long period (years).