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: 107a89,23963231b5359f74 X-Google-Attributes: gid107a89,public X-Google-Thread: 11440e,23963231b5359f74 X-Google-Attributes: gid11440e,public X-Google-Thread: 103376,23963231b5359f74 X-Google-Attributes: gid103376,public X-Google-Thread: 10a146,23963231b5359f74 X-Google-Attributes: gid10a146,public X-Google-Thread: 101deb,23963231b5359f74 X-Google-Attributes: gid101deb,public X-Google-ArrivalTime: 2001-06-07 19:41:31 PST Path: archiver1.google.com!newsfeed.google.com!sn-xit-02!supernews.com!newsfeed.direct.ca!look.ca!newsfeed.icl.net!diablo.netcom.net.uk!netcom.net.uk!newspeer.clara.net!news.clara.net!server3.netnews.ja.net!newshost.central.susx.ac.uk!news.bton.ac.uk!not-for-mail From: John English 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 02:44:55 +0100 Organization: University of Brighton Message-ID: <3B202E17.7C728B66@brighton.ac.uk> 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> NNTP-Posting-Host: dialin-b8.bton.ac.uk Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit X-Trace: saturn.bton.ac.uk 991964678 15323 194.81.199.188 (8 Jun 2001 01:44:38 GMT) X-Complaints-To: news@bton.ac.uk NNTP-Posting-Date: 8 Jun 2001 01:44:38 GMT X-Mailer: Mozilla 4.6 [en] (Win95; I) X-Accept-Language: en Xref: archiver1.google.com comp.lang.ruby:10468 comp.lang.ada:8377 comp.lang.awk:2875 comp.lang.clarion:21390 comp.lang.java.programmer:74592 comp.lang.pl1:880 comp.lang.vrml:3619 Date: 2001-06-08T01:44:38+00:00 List-Id: Roedy Green wrote: > > On Thu, 07 Jun 2001 09:10:44 +0100, John English > wrote or quoted : > > >That way my "commentary" is checkable by the compiler. > > This is one of the big arguments for design by contract rather than > using comments to describe the rules for what methods will eat and > produce. > > There a philosophical problem that Jonathan Revusky and I have tussled > over. When writing JavaDoc, should it be complete, or should it > contain only unexpected information? > > We both agree that JavaDoc of this form: > > "getSize gets the Size" > > Is a waste of effort. You have to think "What would a reasonable human > not know about this parameter or method, that he would reasonably want > to know?" Indeed. Saying "the size" tells you nothing you don't already know... > So you might create a comment of the form: > > "getSize gets the number of elements currently in the collection, not > counting free slots." ... but this tells you what "the size" really means, and so is useful. An assertion could provide the same information, but in current forms of assertions would be less readable that the natural language equivalent. > however, sometimes there is nothing really useful you could add: > e.g. > > "getZipPlusFive get the US Zip+5 postal code." 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 CS101 that American educators toss around). I also had to have "soccer mom" translated -- it appeared in an article in CACM, and a letter to the editor produced a null response since it was presumably too obvious to answer. (Off topic: OTOH, Americans talk about "soccer" instead of "football", but the game they call "football" is played mainly by picking the ball up and running like hell instead of using the feet. Another example of misleading documentation provided by an ill-chosen identifier? :-) Yours very Englishly... ----------------------------------------------------------------- John English | mailto:je@brighton.ac.uk Senior Lecturer | http://www.it.bton.ac.uk/staff/je Dept. of Computing | ** NON-PROFIT CD FOR CS STUDENTS ** University of Brighton | -- see http://burks.bton.ac.uk -----------------------------------------------------------------