I agree, these are cases when you need comments inlined in the code. Describing what a single code is doing is only useful, if the comment is easier to read th

I agree, these are cases when you need comments inlined in the code. Describing what a single code is doing is only useful, if the comment is easier to read than the code itself. That can be useful for arcane cases, such as dirty regular expressions, bash scripts with several layers of pipes, or non-standard pointer manipulation in C. Much more important, is the why, as in your example. But there is also the what when it applies to code design that spans more than a few lines of code. This requires documentation. As long as we follow a design pattern, the documentation is covered by the pattern description. But if we invent a novel design, either a one-off or a new design pattern, it needs to be described in text and figures, not just inline in the code. Similarly, and even to some extent when staying inside a design pattern, object models need a conseptual design, where the ideas and purposes behind each class or interface is explained, as well as where the relationships between classes are visualised.