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

[Chris Burrows]

On Sat, May 14, 2022 at 7:04 AM Skulski, Wojciech <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.

A quick search came up with this article which explains the relevant
issues, with examples, quite well:

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

However, if I have to choose between

(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.

Regards,
Chris Burrows
CFB Software
https://www.astrobe.com/RISC5
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.inf.ethz.ch/pipermail/oberon/attachments/20220514/61d650ec/attachment.html>