Since my blog touches clean code topics a lot, I often mention maintainability. In turn, readability plays a major part in maintainability, since what we can’t read properly, we can’t analyze, debug, fix, refactor and extend properly either. But who defines what is readable and what is not?

This morning I read a tweet by “STL”, touching an aspect of code quality.

Don’t help the compiler: avoiding unnecessary parentheses (when precedence is obvious) improves code by making necessary parens stand out.

— Stephan T. Lavavej (@StephanTLavavej) November 18, 2015

Obviously he is right. Avoiding unnecessary extra stuff like extra parentheses makes code simpler and easier to read. Ironically, the crucial point in this statement is inside parentheses: That extra stuff is only unnecessary if the code is still obvious when you leave it away.

Obvious to whom?

Let’s stick to the example: Parentheses and operator precedence. The precedence of multiplicative and additive operators in C++ is the same as it is for basic arithmetics. So there will be no surprise if you write `a + b * c`, unless you have a very young reader who does not have much experience with basic maths yet.

But what about e.g. the precedence of logic operators: `a || b && c`. If you have implemented a DSL that uses similar logic operators with the same precedence as C++ it is obvious that `&&` has higher precedence and therefore this expression is the same as `a || (b && c)`.

However, the majority of programmers never needed to care about such details, nor do they want to. Therefore style guides often encourage the use of parentheses for such cases, and some compilers even emit a warning if you don’t. In other words, what is obvious to some, need not be obvious to others.

@StephanTLavavej the crux is between your parentheses: when precedence is obvious depends largely on experience/knowledge of the reader.

— Arne Mertz (@arne_mertz) November 18, 2015

Write for the maintainers

The above does not mean you should write code that is readable for absolute beginners, unless you actually are writing for them. Write in a way that is appropriate for your team. They are the ones who will read and maintain and ideally own the code you write.

Writing for your team means you should know approximately what level of knowledge they have in the language you use. I emphasize “know” here, because just making assumptions does not quite cut it, and I use knowledge instead of experience here, because spending time with a language does not necessarily mean learning much about advanced topics.

I have seen seasoned programmers who only superficially knew about templates, and I have seen people with less than a year experience happily hacking away at brain twisting template metaprograms.

How can we make sure that we write code at the right level of clarity and simplicity? I see two ways. First, if you are new to a team, read existing code. The level of knowledge that is present in a team can be seen in the code base that team has been maintaining, so you can just add your code in the same styles they used.

A second tool is to either pair program with team members or at least have them review your code. Be present when they do, instead of just sending them the code for review. That way you can get immediate feedback if you used code that is hard to read for them, and the other way round you can learn from them if there are easier and clearer way to do things.

Challenge them a bit

If you see code that can be written in a way that is simpler but slightly more challenging to read, consider to use that new way. However, before you do so, ask why they didn’t do it before, there might be reasons.

If you use that simpler, more challenging style, make sure to communicate it to your team, maybe hold a little presentation. That way everyone stays on the same page and you enable them to use what they learned.

Don’t take too big steps. People have a certain pace when they are learning new things, and when the gap becomes too large, they might give up. This would essentially leave you in charge of what you wrote instead of the whole team.

Conclusion

Readability can be subjective, and, as a result, at least a small part of the distinction of what is clean, maintainable and readable and what is not, depends on who reads our code. Therefore, make it readable not only for yourself, but also keep in mind everyone else who is likely to read it.