From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00 autolearn=ham autolearn_force=no version=3.4.4 X-Google-Language: ENGLISH,ASCII-7-bit X-Google-Thread: 10ad19,23963231b5359f74 X-Google-Attributes: gid10ad19,public X-Google-Thread: 101deb,23963231b5359f74 X-Google-Attributes: gid101deb,public X-Google-Thread: 11440e,23963231b5359f74 X-Google-Attributes: gid11440e,public X-Google-Thread: 103376,23963231b5359f74 X-Google-Attributes: gid103376,public X-Google-Thread: 1073c2,23963231b5359f74 X-Google-Attributes: gid1073c2,public X-Google-Thread: 10a146,23963231b5359f74 X-Google-Attributes: gid10a146,public X-Google-Thread: 107a89,23963231b5359f74 X-Google-Attributes: gid107a89,public X-Google-ArrivalTime: 2001-06-08 08:22:39 PST Path: archiver1.google.com!newsfeed.google.com!sn-xit-02!supernews.com!newsfeed.direct.ca!look.ca!newshub2.rdc1.sfba.home.com!news.home.com!news1.rsm1.occa.home.com.POSTED!not-for-mail Message-ID: <3B20EDAC.5A4F7BD4@home.com> From: "Donald L. Dobbs" X-Mailer: Mozilla 4.77 [en] (Win98; U) X-Accept-Language: en MIME-Version: 1.0 Newsgroups: comp.lang.ruby,comp.lang.ada,comp.lang.awk,comp.lang.clarion,comp.lang.java.programmer,comp.lang.pl1,comp.lang.vrml Subject: Re: Commenting code References: <9f8b7b$h0e$1@nh.pace.co.uk> <9f8r0i$lu3$1@nh.pace.co.uk> <9fgagu$6ae$1@nh.pace.co.uk> <9fjgha$blf$1@nh.pace.co.uk> <35mqhtkdfma2rggv1htcaq6vfn2ihs67a1@4ax.com> <3B1E1452.BAFAAB7F@baesystems.com> <3B1E4B93.7FB8A94D@lmtas.lmco.com> <3B1F3704.C7E0D03A@brighton.ac.uk> <3b20d633$8$fuzhry$mr2ice@va.news.verio.net> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Date: Fri, 08 Jun 2001 15:22:35 GMT NNTP-Posting-Host: 24.21.61.2 X-Complaints-To: abuse@home.net X-Trace: news1.rsm1.occa.home.com 992013755 24.21.61.2 (Fri, 08 Jun 2001 08:22:35 PDT) NNTP-Posting-Date: Fri, 08 Jun 2001 08:22:35 PDT Organization: Excite@Home - The Leader in Broadband http://home.com/faster Xref: archiver1.google.com comp.lang.ruby:10499 comp.lang.ada:8425 comp.lang.awk:2913 comp.lang.clarion:21460 comp.lang.java.programmer:74805 comp.lang.pl1:919 comp.lang.vrml:3657 Date: 2001-06-08T15:22:35+00:00 List-Id: "Shmuel (Seymour J.) Metz" wrote: > > In , on 06/07/2001 > at 09:58 PM, Roedy Green said: > > >Assembler commenting requires that you be able to follow the logic > >without looking at ANY of the code. > > No way! That just obscurs the code and makes it less likely that > errors will be spotted. As one who spends about half and half between assembler language (firmware situations) and higher level languages (PL/I, VB, etc.) I must chime in. The comments are absolutely necessary in Assembler, to wit: label: ADC A,$01 This is a perfectly good instruction to do an add with carry to the accumulator A. So what? But if you add the comment "Increment the shaft encoder counter until limit reached" then I have some idea of what the code is SUPPOSED to be doing and how that snippet of code relates to the overall problem to be solved. > > >Without a complete picture of what > >is going on in the comments, it is very difficult to find the code > >you are looking for. > > Au contraire; with a complete picture you can't see the forrest for > the trees. At the beginning of each section of code (or function or subroutine) the "forest" is described. The comments on each line of code describe the individual trees. It's sort of a drill down approach but highly effective. Somewhere comments must always include purpose, circumstance, rationale, requirements, constraints, algorithms, etc. If I have that then I have a baseline and a point of departure if debugging is required. >Comments should explain the code, not echo it. Some authors > have gone so far as to insist on covering the comments while reviewing > the code to ensure that the reviewer is not mislead by the comments. > > -- > ----------------------------------------------------------- > Shmuel (Seymour J.) Metz, SysProg and JOAT > Atid/2 > Team OS/2 > Team PL/I > > Any unsolicited commercial junk E-mail will be subject to legal > action. I reserve the right to publicly post or ridicule any > abusive E-mail. > > I mangled my E-mail address to foil automated spammers; reply to > domain acm dot org user shmuel to contact me. Do not reply to > spamtrap@library.lspace.org > -----------------------------------------------------------