What Is The Legibility Argument?

When “legibility” depends on who sees it

The blurred picture of a beach with a coconut tree on the right

Discussions are a fundamental part of software development, they are a necessary friction to increase scalability. A few patterns can emerge from those discussions that allow us to spot problems early when those problems can have an impact on the quality of the outcome. One of them is the Legibility Argument.

We should always strive to write legible code, but what does “legible” mean anyway?

There are many general guidelines in the software industry regarding design patterns, architectures, and principles that are supposed to document solutions for specific problems. But when we talk about legibility we are also talking about naming things. In this case, it is mostly a human judgment that can't be easily defined outside each specific context. Naming things is a hard thing to do.

Naming things is hard because choosing a good name can't be easily done outside the specific context of a problem and outside the biased view of the author

The Legibility Argument happens when the author of a piece of code claims that the code they wrote is legible, which is a bad smell in a discussion. The author will always believe the code they wrote is legible because they already understand it all. They have the whole context that somebody who will read the code in the future don't.

There’s a psychological effect called the Hindsight Bias. The effect happens when people tend to see an event as predictable after it has happened. When looking at a code written in the past, the author will tend to believe the code they wrote could have been made better if they had the information they have at the moment of the hindsight.

There's another psychological effect called the Curse Of Knowledge. The effect happens when people tend to ignore knowledge they have but others don’t when reaching a conclusion. The author of a piece of code will tend to believe their work will be perfectly understandable because they have the knowledge necessary to understand it (their mental context on the solution). After a few months or years, when acting in hindsight looking at the same code without the same mental context, they will find legibility problems but will believe they could have made it better at the time. This often leads to refactoring, which makes the developer recreate the mental context and potentially do the same mistake over again.

The author always tends to believe their code is legible, and when acting in hindsight will tend to believe they could have made it better

This is very similar to the Black swan theory. According to Wikipedia, to identify a black swan event the following should be true:

1. The event is a surprise (to the observer).
2. The event has a major effect.
3. After the first recorded instance of the event, it is rationalized by hindsight, as if it could have been expected; that is, the relevant data were available but unaccounted for in risk mitigation programs. The same is true for the personal perception by individuals.

If we rely on the author, they will need to wait months or years for the mental context to vanish so that they can perceive something they wrote from an unbiased view and fix it if necessary. It's impracticable to wait all that time to be able to make sure the author is developing the most legible software for posterity.

The solution is asking for feedback.

The author can ask for feedback from an unbiased team member that is not working on that piece of code and have no context whatsoever regarding the requirements or the thoughts behind the architecture. The chances of receiving a quality feedback is higher. If the feedback disagrees with the author's view, it is also possible to ask for a third person to see if the feedback will be the same. If it does, then it is much more likely that the author's argument was not so strong.

This technique of carrying at least 3 samples to increase the chances of achieving a better, more legible, solution is called Triangulation, a technique that is also used when testing.

The best way to achieve a deterministic legibility result is to ask feedback for someone that has no context on what is being done

Legibility claims are more likely to yield an undesired result when they come from the author of the code. The best way to minimize this problem is run a small experiment with a few individuals that have no context on the code to judge whether it's legible or not. It can be on Code Review phase or before it, but the important thing is that the author receives an independent feedback on their work before claiming that it's legible.

The Legibility Argument is more likely to yield an undesired result if it comes from the author of the code

Writing legible code is not easy. The best we can do is asking for feedback to improve our own heuristics and do it better next time.

Don't try to do everything alone. We're all still humans.


Thanks for reading. If you have some feedback, reach out to me on Twitter, Facebook or Github.