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

Skulski, Wojciech skulski at pas.rochester.edu
Sat May 14 03:27:23 CEST 2022


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.



More information about the Oberon mailing list