What makes a program code maintainable

What distinguishes readable code?

While writing code, as a developer you primarily make sure that the code works. How easy to read the code is is often of secondary importance. But in the long term, legibility is precisely what determines the maintainability of code. So what are the characteristics of good readability?

Programming is a cognitively challenging activity. It requires a high degree of abstraction and systematic thinking. In addition, the problems to be solved are difficult, from a professional and often also from a technical point of view. The effect of this is that when you write code you are focused on understanding the problem and finding the solution.

Götz & Golo

"Götz & Golo" is a joint series by Götz Martinek and Golo Roden. One is the managing director of sodge IT GmbH, the other CTO of the native web GmbH. What unites the two is their great passion for software development. Since September 2019, they have been tackling a monthly topic on which everyone then describes their individual perspective without knowing each other's article in advance. The related article by Götz can be found on the Sodge IT blog. The question asked for this article was: "What distinguishes readable code?"

What one often thinks less about when writing code in a concentrated manner is its readability. The thoughts revolve around the underlying problem and its solution to such an extent that the external form of the solution becomes a minor matter.

The reason for this is obvious: Since you deal so intensively with the actual problem while writing, good legibility is not necessary in order to understand the problem or its solution.

Optimizing for the future me

Of course, this does not apply to other developers. They lack regular and intensive preoccupation with the topic - and the same applies to their own future self.

Now you could say that it is easy to remedy this problem: after you have written the code, you just have to revise it again with a view to readability and traceability. But that does not happen in the vast majority of cases. Why not?

The answer to this question is very simple: Since in many cases it was time consuming to even solve the problem itself, there is now no time to make the result "pretty". Since this does not directly contribute to the number of features developed, improving legibility is put on the back burner as a supposedly optional.

Incomprehensible code is difficult to maintain

In the long term, however, this approach will pay off. Because if you can no longer read and understand code and therefore no longer understand it, it becomes extremely difficult to maintain and further develop it.

Now there are numerous levels of discussion about what characterizes readable code and how it can be improved. A simple metric, however, is that code is easy to read when someone else can understand what the code is doing and why he is doing it with little effort. So it is ultimately about optimizing the traceability.

You can talk about the architecture of the overall project as well as about each individual line. However, what you as a developer have direct influence on is the individual line, both of the code that you rewrite and of the code that you find and can improve according to the boy scout rule.

Five rules

In the following, five rules are presented that do not claim to be complete, but have proven themselves in everyday life:

  • Code should follow a uniform formatting that is enforced either via a linter or automatic formatting. The less space there is for individual style in indentation, blank lines, parentheses and the like, the less one has to think about why code is formatted this way or that.
  • Variable and function names should be chosen from a technical and not a technical point of view and should reflect the original intention. That also means in identifiers for words like service and Manager to refrain if possible, as they have little informative value, and to replace them with stronger terms.
  • Code within a function should be at roughly the same level of detail. If the level of detail differs greatly between individual lines, it is advisable to outsource the more specific lines to a function and to give it a technically meaningful name.
  • Technically, there is basically nothing against using advanced language constructs - however, this must never be an end in itself. In case of doubt, one should prefer the somewhat simpler construct to the more demanding one, even if it takes longer to write. Shortness alone does not lead to better readability - the opposite is often the case.
  • Comments shouldn't do that What document, but that Why: What the code does, the code itself should describe in a readable and comprehensible way, but why the code was written in a certain way and which trade-offs were made, that should be in a comment.

Conclusion

As I said, the rules presented do not claim to be exhaustive and, as always, there are of course legitimate exceptions to these rules. Nevertheless, they offer a good first reference point and are sometimes not as easy to fulfill as it seems at first glance. The requirement to choose technically speaking identifiers alone is sometimes not that easy.

But those who follow these rules come closer to the goal of writing legible and comprehensible code than whoever ignores them completely.

tl; dr: Legibility is synonymous with comprehensibility. Little emphasis is placed on this when writing code because the mind is busy solving a challenging problem. Nevertheless, there are rules that you should follow as a basis in order to avoid at least the grossest blunders.

Golo Roden

Golo Roden is the founder, CTO and managing director of the native web GmbH, a company specializing in native web technologies.

Read CV »