Programmer Musings

BPGB: Readable Code

As you probably know, code is read more often than it is written. Anybody who has worked on code written by anyone else has probably wished that the code were more readable at some point.

Writing readable code should definitely be considered a best practice. The problem comes when defining what you mean by readable.

The Clever Coder

The situation that normally causes a readable code mandate is normally one or a small number of people making code that is hard for the team to read. Let's call this person the Clever Coder. This programmer loves obscure features of the language and uses them whenever he can. He is likely to use unusual algorithms with the justification that the are more efficient or robust without proving those assertions. His code often contains obscure references or jokes that are only familiar to a small number of people. These references rarely have any connection with the actual purpose of the code.

At some point, someone else has to deal with this guy's code and the resulting complaints (and probably bugs from obscure interactions of changes) causes someone in authority to mandate Thou shalt write readable code.

How to Define Readable

So who determines what is readable code? If you define readable as code that your current team considers as readable, this mandate is not too bad. If you have code that must be understandable to people outside your team, you could get input from them.

Unfortunately, since the problem is normally caused by someone clever writing code that's completely obtuse, the normal counter response is normally to go too far in the other direction: the code should be readable by as many people as possible.

The Novice Assumption

At this point, someone usually decides to approach readability by one of two measures.

• Can the manager read it?

• Can some hypothetical new programmer read it?

If the manager was recently a tech type on this code base, her insight might still be good. If not, we have what is effectively a non-native speaker determining the readability of the code. As you can guess, this may not turn out well.

The problem with the hypothetical new programmer is that this usually quickly devolves to the an assumption of someone completely unfamiliar with the code and the language. The result is an assumption that the code must be readable by anyone who just walks in the door. The kind of lowest common denominator standard guarantees verbose and awkward code.

Lowest Common Denominator

The worst versions of this I have seen involve mandating that the code should be perfectly clear to someone who is not even familiar with the language. (If that seems silly, I agree. But, I have seen that requirement before.)

This results in code that is horrible from the viewpoint of someone with any level of experience in the language. It's usually unnecessarily verbose, but every little detail is spelled out in excruciating detail. This view is often pushed by the people with the least experience in the language or code base or by managers who once programmed in a completely different environment.

The Self-Fulfilling Prophecy

One result of a code base written to be readable by the least experienced person we can imagine is that the only people who will be willing to work on it are those people with the least experience. Your more senior developers will avoid this code if possible. If they can't avoid the code, they will leave for places where they can work more effectively. Before long. your code will be maintained by people who are only comfortable with code where everything is spelled out in detail.

Now, all code must be written in this style because the programmers that remain can only work this way.

The Trade-off

I've actually written several posts on this topic in the past. Choosing the audience you are using for defining readability has a strong effect on who will be willing and able to work on your code. Not realizing that different parts of your code may have different audiences, requires that everything must be written to the lowest common denominator.

Aiming for a simpler standard of readability guarantees that more people can read it in the same way that drivel on TV guarantees a wider audience. Aiming for a more advanced level of readability reduces the number of people who can read the code, but that audience will necessarily be more advanced. Readability becomes a filter. On the opposite side of the lowest common denominator, we are back with the original example of code that can only be read by an audience of one. Like everything else in programming, readability involves trade-offs.

Conclusion

Readability becomes a BPGB when we don't think about the audience we are targeting. As usual, best practices must be applied thoughtfully to actually be best practices.

The Best Practices Gone Bad series contains more explorations of best practices taken to unfortunate conclusions.