[Oberon] Commenting code (was: Impartial observation? ...)

[Skulski, Wojciech]

Chris:

>https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/

Looks like a reasonable article, in a reasonable agreement with van Tassel. 

>However, if I HAVE TO CHOOSE between (capitalization is mine -- WS)

>(a) Sparsely commented code accompanied by separate detailed 
>  design documentation including graphics, table of contents etc. 
>  created using a Word processor
> and
>(b) Liberally-commented code accompanied by minimal notes 
>  created using a programmer's editor
> give me (a) any day.

Why do you need to CHOOSE? A good Word-based documentation (or Wiki, or anything else) does not preclude comments in the code. 

At the end of the day it boils down to efficiency of our work. There are those who can parse uncommented  RISC5-style Verilog in their minds. Good for them. I cannot. My interns cannot. My employees cannot.  Why do we need to accept the style of those few who can, if it is impacting our projects because we cannot? 

If my employee was producing multi-level ternary operators and refused to write down what the code was doing, then it would impact our progress. We need clear code and good comments to pursue our projects.

W.