<div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Sat, May 14, 2022 at 7:04 AM Skulski, Wojciech <<a href="mailto:skulski@pas.rochester.edu">skulski@pas.rochester.edu</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><br>
>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: <br>
<br>
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.<br></blockquote><div><br></div><div>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.</div><div><br></div><div>A quick search came up with this article which explains the relevant issues, with examples, quite well:</div><div><br></div><div><a href="https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/">https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/</a><br></div><div><br></div><div><div>However, if I have to choose between </div><div><br></div><div>(a) Sparsely commented code accompanied by separate detailed design documentation including graphics, table of contents etc. created using a Word processor </div><div>and </div><div>(b) Liberally-commented code accompanied by minimal notes created using a programmer's editor</div><div><br></div><div>give me (a) any day.</div></div><div><br></div><div>Regards,</div><div>Chris Burrows</div><div>CFB Software</div><div><a href="https://www.astrobe.com/RISC5">https://www.astrobe.com/RISC5</a></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div></div></div>