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: 1073c2,23963231b5359f74 X-Google-Attributes: gid1073c2,public X-Google-Thread: 101deb,23963231b5359f74 X-Google-Attributes: gid101deb,public X-Google-Thread: 10a146,23963231b5359f74 X-Google-Attributes: gid10a146,public X-Google-Thread: 107a89,23963231b5359f74 X-Google-Attributes: gid107a89,public X-Google-Thread: 103376,23963231b5359f74 X-Google-Attributes: gid103376,public X-Google-Thread: 11440e,23963231b5359f74 X-Google-Attributes: gid11440e,public X-Google-ArrivalTime: 2001-06-14 09:22:50 PST Path: archiver1.google.com!newsfeed.google.com!sn-xit-02!sn-xit-01!supernews.com!newshub2.rdc1.sfba.home.com!news.home.com!news1.rsm1.occa.home.com.POSTED!not-for-mail Message-ID: <3B28E4BA.551784C1@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> <3B27AD17.DF50BDED@home.com> <3b28b178$7$fuzhry$mr2ice@va.news.verio.net> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Date: Thu, 14 Jun 2001 16:22:47 GMT NNTP-Posting-Host: 24.21.61.2 X-Complaints-To: abuse@home.net X-Trace: news1.rsm1.occa.home.com 992535767 24.21.61.2 (Thu, 14 Jun 2001 09:22:47 PDT) NNTP-Posting-Date: Thu, 14 Jun 2001 09:22:47 PDT Organization: Excite@Home - The Leader in Broadband http://home.com/faster Xref: archiver1.google.com comp.lang.ruby:10585 comp.lang.ada:8734 comp.lang.awk:3057 comp.lang.clarion:21931 comp.lang.java.programmer:76358 comp.lang.pl1:1030 comp.lang.vrml:3799 Date: 2001-06-14T16:22:47+00:00 List-Id: "Shmuel (Seymour J.) Metz" wrote: > > In <3B27AD17.DF50BDED@home.com>, on 06/13/2001 > at 06:13 PM, "Donald L. Dobbs" said: > > >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. > > None of which has anything to do with assembler language per se; the > same consideerations apply to Ada, BASIC, COBOL, FORTRAN, ICON, LISP, > PERL, SETL or whatever. > But, of course! And I practice what I preach regardless of the language to make life a little easier on the person who may end up having to support my code somewhere down the road. > -- > ----------------------------------------------------------- > 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 > -----------------------------------------------------------