I would posit that the vacuous comments that you say to eschew are a harmful superfluity. Certainly if I have to teach another programming course, I will announce at the beginning of the term that points will be taken off for such comments. I'll also warn that if the code can't be understood by the other students that I will make a judgement call as to whether the algorithm is intrinsically hard to understand or whether it is opaquely explained., with points off for the latter.
If anybody still has access to the source code for FAP, take a look at the symbol table sort. I found it to be a masterpiece of clarity. It's usually the code or the comments that are at fault rather than the underlying algorithm. -- Shmuel (Seymour J.) Metz http://mason.gmu.edu/~smetz3 ________________________________________ From: IBM Mainframe Discussion List <[email protected]> on behalf of Jesse 1 Robinson <[email protected]> Sent: Thursday, November 29, 2018 11:51 AM To: [email protected] Subject: Re: Compute the maximum return code of all steps (so far) A brief ode to comments. I'm also wary of bureaucratic dicta requiring comments on every line, but I will always tilt in favor of more comments rather than fewer. It's hard to imagine a harmful superfluity. The real dictum should be to eschew vacuous comments like 'add r4 to r3'. Duh. If I can read ASM, I can see what that line is doing. If I cannot read ASM, then the comment is absurdly inappropriate. Good comments should be intelligible to anyone with experience in IT. That is not a trivial goal but one that's neither unreasonable nor unverifiable. . . J.O.Skip Robinson Southern California Edison Company Electric Dragon Team Paddler SHARE MVS Program Co-Manager 323-715-0595 Mobile 626-543-6132 Office ⇐=== NEW [email protected] -----Original Message----- From: IBM Mainframe Discussion List [mailto:[email protected]] On Behalf Of Seymour J Metz Sent: Tuesday, November 27, 2018 11:31 AM To: [email protected] Subject: (External):Re: Compute the maximum return code of all steps (so far) I certainly don't advocate a bureaucratic rule like "put a comment on every line", but that code really needs more comments. Variable names like P1, P2, P3 don't help either. -- Shmuel (Seymour J.) Metz http://mason.gmu.edu/~smetz3 <snip all> ---------------------------------------------------------------------- For IBM-MAIN subscribe / signoff / archive access instructions, send email to [email protected] with the message: INFO IBM-MAIN ---------------------------------------------------------------------- For IBM-MAIN subscribe / signoff / archive access instructions, send email to [email protected] with the message: INFO IBM-MAIN
