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: 107a89,23963231b5359f74 X-Google-Attributes: gid107a89,public X-Google-Thread: 11440e,23963231b5359f74 X-Google-Attributes: gid11440e,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-Thread: 101deb,23963231b5359f74 X-Google-Attributes: gid101deb,public X-Google-ArrivalTime: 2001-06-08 09:56:14 PST Path: archiver1.google.com!newsfeed.google.com!sn-xit-02!supernews.com!newsfeed.direct.ca!look.ca!newsfeed.icl.net!npeer.kpnqwest.net!lnewspeer00.lnd.ops.eu.uu.net!lnewspost00.lnd.ops.eu.uu.net!emea.uu.net!not-for-mail From: Jon Skeet 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, 8 Jun 2001 17:45:14 +0100 Message-ID: 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> Organization: Peramon Technology Ltd. X-Newsreader: MicroPlanet Gravity v2.30 NNTP-Posting-Host: fw.peramon.com X-Trace: 992018717 reading.news.pipex.net 15026 193.132.195.125 X-Complaints-To: abuse@uk.uu.net Xref: archiver1.google.com comp.lang.ruby:10504 comp.lang.ada:8433 comp.lang.awk:2919 comp.lang.clarion:21468 comp.lang.java.programmer:74833 comp.lang.pl1:924 comp.lang.vrml:3663 Date: 2001-06-08T17:45:14+01:00 List-Id: Ray Blaak wrote: > Roedy Green writes: > > 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? > > It should only contain the unexpected information. Let the code describe > itself as much as possible, as you pointed out. By "the code", do you actually mean "the signature"? I'd rather not have to go to the code itself in order to find out what a method does, even if the code itself makes it crystal clear. -- Jon Skeet - http://www.pobox.com/~skeet/ If replying to the group, please do not mail me too