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: 11440e,23963231b5359f74 X-Google-Attributes: gid11440e,public X-Google-Thread: 101deb,23963231b5359f74 X-Google-Attributes: gid101deb,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-13 11:13:07 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: <3B27AD17.DF50BDED@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> <3B20EDAC.5A4F7BD4@home.com> <3b27569c$1$fuzhry$mr2ice@va.news.verio.net> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Date: Wed, 13 Jun 2001 18:13:06 GMT NNTP-Posting-Host: 24.21.61.2 X-Complaints-To: abuse@home.net X-Trace: news1.rsm1.occa.home.com 992455986 24.21.61.2 (Wed, 13 Jun 2001 11:13:06 PDT) NNTP-Posting-Date: Wed, 13 Jun 2001 11:13:06 PDT Organization: Excite@Home - The Leader in Broadband http://home.com/faster Xref: archiver1.google.com comp.lang.ruby:10570 comp.lang.ada:8679 comp.lang.awk:3040 comp.lang.clarion:21838 comp.lang.java.programmer:76038 comp.lang.pl1:1005 comp.lang.vrml:3770 Date: 2001-06-13T18:13:06+00:00 List-Id: "Shmuel (Seymour J.) Metz" wrote: > > In <3B20EDAC.5A4F7BD4@home.com>, on 06/08/2001 > at 03:22 PM, "Donald L. Dobbs" said: > > >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. > > Nu? In what way does that echo the code? If, instead, you add the > comment "increment the accumulator with carry", would you defend the > comment as necessary? > Of course "increment the accumulator with carry" as a comment doesn't tell me anything more than I can already discern by looking at the code. The point I'm trying to make is that I am handed some assembly language code written by someone else in a different country in a different time zone who is a junior programmer and didn't do a decent job of documenting his program. He's generally unavailable and uncooperative. [This is an actual case.] His code has a bug in it. I have to fix it on my own. Unless there is some documentation somewhere (preferably near the code) that tells what the program is SUPPOSED to do and the rationale of his code as how he implemented a solution, my job really becomes tough because I have no baseline. I can look at the code and see what bit fiddling it actually does. But is that what it is supposed to be doing? Properly documented code allows me to get to the heart of the problem rapidly; otherwise it becomes a big job of reverse engineering. > -- > ----------------------------------------------------------- > 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 > -----------------------------------------------------------