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-7-bit X-Google-Thread: 10ad19,23963231b5359f74 X-Google-Attributes: gid10ad19,public X-Google-Thread: 107a89,23963231b5359f74 X-Google-Attributes: gid107a89,public X-Google-Thread: 101deb,23963231b5359f74 X-Google-Attributes: gid101deb,public X-Google-Thread: 1073c2,23963231b5359f74 X-Google-Attributes: gid1073c2,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-07 16:17:25 PST Path: archiver1.google.com!newsfeed.google.com!sn-xit-02!supernews.com!nntp-relay.ihug.net!ihug.co.nz!news-hog.berkeley.edu!ucberkeley!enews.sgi.com!newshub2.rdc1.sfba.home.com!news.home.com!news1.rdc1.bc.home.com.POSTED!not-for-mail From: Roedy Green Newsgroups: comp.lang.ada,comp.lang.awk,comp.lang.clarion,comp.lang.java.programmer,comp.lang.pl1,comp.lang.vrml Subject: Re: Commenting code Organization: Canadian Mind Products Reply-To: roedy@mindprod.com Message-ID: <1b20it82mnk73tdrv896i50f2oqv9ttsu6@4ax.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> X-Newsreader: Forte Agent 1.8/32.548 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Date: Thu, 07 Jun 2001 23:17:23 GMT NNTP-Posting-Host: 24.76.128.193 X-Complaints-To: abuse@home.net X-Trace: news1.rdc1.bc.home.com 991955843 24.76.128.193 (Thu, 07 Jun 2001 16:17:23 PDT) NNTP-Posting-Date: Thu, 07 Jun 2001 16:17:23 PDT Xref: archiver1.google.com comp.lang.ada:8371 comp.lang.awk:2869 comp.lang.clarion:21378 comp.lang.java.programmer:74552 comp.lang.pl1:877 comp.lang.vrml:3616 Date: 2001-06-07T23:17:23+00:00 List-Id: 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. 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 problem comes that so many things are for expediency are considered as primitives in Java that really are logically types, e.g. treating ZipPlus5 as just a String. There then is not a natural central place to define and document them. Again, in future I would hope SCIDS http://mindprod.com/scid.html would come to the rescue so that the definition would be only a click or two away when you wanted it. It could not get out of sync, because there is logically only one copy of it. For more detail, please look up the key words mentioned in this post in the Java Glossary at: http://mindprod.com/gloss.html If you don't see what you were looking for, complain! or send your contribution for the glossary. -- Roedy Green, Canadian Mind Products Custom computer programming since 1963. Ready to take on new work.