A Philosophy of Software Design Vs. Clean Code

This is a useful debate.

UB dislikes comments because they may differ from what the code actually does, and JO likes comments because they say some things not explicitly written in the code.

Their two ways can be reconciled as follows: I'd say comments and code co-describe what the developer's intentions are to the human reader, but since the comments are ignored by the machine, only the code has "normative" nature (to use the language of standards/regulations). Ironically, in their debate they both ignore what Knuth considers his greatest accomplishment of his career: literate programming, which is a single view/representation that can be automatically compiled to serve its two audiences: human (LaTeX) and machine (code, obviously no comments needed as they are ignored): literate programming also solves one key point expressed by UB, namely that to understand comments, you must already have understood how the code works. This is not true for literature programming. To paraphrase Knuth quoting Wikipedia:

  "[L]iterate programming provides higher-quality programs, since it forces programmers to explicitly state the thoughts behind the program, making poorly thought-out design decisions more obvious. Knuth also claims that literate programming provides a first-rate documentation system, which is not an add-on, but is grown naturally in the process of exposition of one's thoughts during a program's creation.[10] The resulting documentation allows the author to restart their own thought processes at any later time, and allows other programmers to understand the construction of the program more easily."

Knuth would not like comments or JavaDoc, as both are ways inferior to literate programming, a way that explains the origins, assumptions, design rationale and construction of the method step by step, and therefore explains why the code looks like it looks, from the author's original motivation.