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: 1073c2,23963231b5359f74 X-Google-Attributes: gid1073c2,public X-Google-Thread: 11440e,23963231b5359f74 X-Google-Attributes: gid11440e,public X-Google-Thread: 107a89,23963231b5359f74 X-Google-Attributes: gid107a89,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!supernews.com!news.gv.tsc.tdk.com!falcon.america.net!sunqbc.risq.qc.ca!howland.erols.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.ruby,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:24:42 +0200 Organization: Dresdner Bank AG Message-ID: <3B20E02A.FEDAC2BD@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> <3B202E17.7C728B66@brighton.ac.uk> <5sf0itoauh0fi1nvq4ll5ljmh3u4fjope1@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.ruby:10492 comp.lang.ada:8414 comp.lang.awk:2905 comp.lang.clarion:21446 comp.lang.java.programmer:74773 comp.lang.pl1:911 comp.lang.vrml:3648 Date: 2001-06-08T16:24:42+02:00 List-Id: Roedy Green wrote: > On Fri, 08 Jun 2001 02:44:55 +0100, John English > wrote or quoted : > >Hmm, I disagree. I'm not an American, so "zip plus 5" means > >absolutely nothing to me (just like other American terms like GPA > >and K-12 and > Bad example for an international audience. ZipPlus5 would be > instantly familiar to any American bean counting programming > team. For the purposes of discussion, (what to do in JavaDoc with > methods and variables that don't desperately need a comment), you > might come up with example methods that need no further elaboration, > either because the vocabulary has a central project glossary > definition or because there in nothing additional you have to say > that is not obvious from the type information or the method/variable > name. Note that all of these still need some comment concerning border conditions: > e.g. > getSecondInitial What does the function return for people who don't have a second initial? (FWIW: this is also an Americanism. In Europe, we don't use anything but the first name and the family name.) > getFaxAreaCode > getSubscriptionExpiryDate What about lifetime subscriptions? > setEstimatedArrivalTime Any preconditions? (What happens, for example, if the estimated arrival time is before the departure time?) In sum, there is almost never a case where you can encode all of the necessary information in the function name. Calling the function "getSecondInitialOrEmptyStringIfNone" is probably carrying things too far, so a short comment would be in order. -- 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