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

[Nemo Nusquam]

On 2022-05-13 20:13, Chris Burrows wrote:
>
>
> On Sat, May 14, 2022 at 7:04 AM Skulski, Wojciech 
> <skulski at pas.rochester.edu <mailto:skulski at pas.rochester.edu>> wrote:
>
>
>     From Van Tassel, "Program Style, Design, Efficiency, Debugging,
>     and Testing", 2nd edition, 1978. Chapter 1, Program Style. The
>     following programming mantra were highlighted by the author:
>
>     Programs are to be read by humans. Provide more comments than you
>     think you will need. Use prologue comments. Use directory comments
>     in long programs. Comments should provide something extra - not
>     just paraphrase the code. Indent comments the same amount as the
>     code they refer to. Incorrect comments are worse than no comments
>     at all.
>
>
> Commentsense (sic) depends on context to some extent. I don't know 
> about COBOL or PL/1, but FORTRAN's naming rules definitely led to the 
> need for more comments than other programming languages.  In a similar 
> era when that book was written, I worked on a software project that 
> was required to follow the programming  rules contained in a Military 
> spec. One of these rules was 'Every line of code must be commented'. 
> It took me the best part of a week to convince the project managers 
> that the rule was not applicable because the spec was written with 
> assembly language in mind, not Pascal.

We used a form of literate programming on a few projects using noweb.  
Norm Ramsey, author of noweb, explains his rationale here: 
https://thenewstack.io/why-literate-programming-might-help-you-write-better-code/ 
(We had the same problem conforming to a milspec.)

N.