Hi Lars. Documentation is very important, yes (although many — who I disagree with — claim that code should be entirely self-documenting).

But the language itself has a large impact on maintainability.

Case in point: A few years ago I had to write code to interface to the REST API of the (then alpha) Docker Registry version 2. Since the documentation was poor (an 80 page spec that was vague in many parts), I had to reverse engineer the code, which was written in Go.

It was an awful experience. The chief problem was that I could not discern what a variable’s type was. In Go, objects don’t have statically declared types. To know the type, you have to determine which methods it implements. I spent hours searching through code, trying to determine what type various variables were. In Java, I would not have had to search.

A similar experience with Python: Years ago I did a deep dive into machine learning. In the course of that I used various machine learning projects created by individuals. Again, since Python does not declare the return type of a method, I had to read the code of the methods: and guess what? Methods themselves call other methods, so I would have to read those; and so on. I spent hours trying to determine what type a method would return.

These were awful experiences, and were entirely the result of the failure of those languages to declare a static return type.

As Guido van Rossum (creator of Python) wrote recently,

“I’ve learned a painful lesson, that for small programs dynamic typing is great. For large programs, you have to have a more disciplined approach. And it helps if the language actually gives you that discipline, rather than telling you, ‘Well, you can do whatever you want.’”