Who are we Writing Code for?

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.

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.

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.

Previous Post
Next Post

4 Comments


  1. Great post ! I totally agree with you.

    From a more global point of view, I think we can say that readability is a matter of code patterns your team is used to, a silly example is about making functions or classes with methods: if your team only write functions, don’t make classes with methods to do things.

    In fact, maybe we could measure readability as a change of patterns from blocks to blocks (of line) or files to files ? The more similar the code is, the faster the code reviewer will go I guess.

    That could be the reason why there is no absolute good coding style.

    Reply

  2. I like what you are saying. Some examples might help. Maybe you could give an example of simpler but more challenging to read code.

    Reply

    1. Well there is the example of leaving away parentheses. Another would be the use of lambdas in a team that is not used to modern C++. Perhaps even leave away the empty parameter list and return type: []{ ... }
      A more general thing is making stuff implicit instead of explicit. It often streamlines code, while the reader will have to know what is happening implicitly. e.g. provide default arguments to already known functions where you often use the same arguments, if those are sensible defaults.

      Reply

Leave a Reply

Your email address will not be published. Required fields are marked *