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=-0.3 required=5.0 tests=BAYES_00, REPLYTO_WITHOUT_TO_CC autolearn=no autolearn_force=no version=3.4.4 X-Google-Language: ENGLISH,ASCII X-Google-Thread: 10ad19,23963231b5359f74 X-Google-Attributes: gid10ad19,public X-Google-Thread: 107a89,23963231b5359f74 X-Google-Attributes: gid107a89,public X-Google-Thread: 1073c2,23963231b5359f74 X-Google-Attributes: gid1073c2,public X-Google-Thread: 101deb,23963231b5359f74 X-Google-Attributes: gid101deb,public X-Google-Thread: 103376,23963231b5359f74 X-Google-Attributes: gid103376,public X-Google-Thread: 10a146,23963231b5359f74 X-Google-Attributes: gid10a146,public X-Google-ArrivalTime: 2001-06-08 07:36:03 PST Path: archiver1.google.com!newsfeed.google.com!sn-xit-02!sn-xit-03!supernews.com!cyclone-sjo1.usenetserver.com!news-out-sjo.usenetserver.com!hub1.nntpserver.com!news-in.nibble.net!news.maxwell.syr.edu!newsfeed00.sul.t-online.de!t-online.de!newsfeed.r-kom.de!feeder01.news.de.uu.net!news-1.bank.dresdner.net!not-for-mail From: James Kanze Newsgroups: comp.lang.ada,comp.lang.awk,comp.lang.clarion,comp.lang.java.programmer,comp.lang.pl1,comp.lang.vrml Subject: Re: Commenting code Date: Fri, 08 Jun 2001 16:17:55 +0200 Organization: Dresdner Bank AG Message-ID: <3B20DE93.A60BD173@dresdner-bank.com> References: <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> <9YvEvCGSa+3g@eisner.encompasserve.org> <1b20it82mnk73tdrv896i50f2oqv9ttsu6@4ax.com> Reply-To: default@dresdner-bank.com NNTP-Posting-Host: ffzj09tz.bank.dresdner.net Mime-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: 8bit X-Mailer: Mozilla 4.7 [en]C-CCK-MCD drebazen10 (WinNT; I) X-Accept-Language: en,fr,de Xref: archiver1.google.com comp.lang.ada:8415 comp.lang.awk:2906 comp.lang.clarion:21447 comp.lang.java.programmer:74774 comp.lang.pl1:912 comp.lang.vrml:3649 Date: 2001-06-08T16:17:55+02:00 List-Id: Roedy Green wrote: > On 7 Jun 2001 18:25:27 -0500, Kilgallen@eisner.decus.org.nospam (Larry > Kilgallen) wrote or quoted : > >The comment I would like to see is what it returns if only the Zip > >code is known and not the additional digits. > In my style of documenting you would NOT document that. That > information belongs in a central project glossary/data directory of > just what a Zip+5 is, and how it is displayed. One meta-comment: just what is zip+5? When Roedy first posted the example, I figured it was just an imaginary example; that the function actually returned the zip code + 5 (e.g.: for ZipCode 30318, it would return 30323). This function obviously has no use (or has no obvious use), but then, silly examples often don't. >From later comments, I get the feeling that my first impression was wrong. > The problem with putting that information on every method is it gets > out of sync too easily, and it would be ponderous to document the > format fully everywhere it is used. If ZipPlus5 were a class, with a > display or toString method, the logical place to document that would > be in the ZipPlus5 class. The question is where the information is treated. If the function goes to some central data base, and returns whatever it finds there, then the fact that it returns a standard format should be documented, but not the format itself. If the function returns a type ZipPlusFive, then any documentation concerning the invariants of that class belong in that class. If the function actually does something itself to generate the results, however, then it should document what it does. Or rather, what it guarantees. -- James Kanze mailto:kanze@gabi-soft.de Conseils en informatique orient�e objet/ Beratung in objektorientierter Datenverarbeitung Ziegelh�ttenweg 17a, 60598 Frankfurt, Germany Tel. +49(069)63198627