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: 103376,23963231b5359f74 X-Google-Attributes: gid103376,public X-Google-Thread: 101deb,23963231b5359f74 X-Google-Attributes: gid101deb,public X-Google-Thread: 10a146,23963231b5359f74 X-Google-Attributes: gid10a146,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-ArrivalTime: 2001-06-08 09:19:25 PST Path: archiver1.google.com!newsfeed.google.com!sn-xit-02!supernews.com!newsfeed.direct.ca!look.ca!newsfeed.bc.tac.net!news.bc.tac.net!not-for-mail Sender: blaak@TORUS 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 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> From: Ray Blaak Message-ID: Organization: The Transcend X-Newsreader: Gnus v5.6.42/Emacs 19.34 Date: 08 Jun 2001 09:18:25 -0700 NNTP-Posting-Host: 208.181.209.61 X-Complaints-To: news@bctel.net X-Trace: news.bc.tac.net 992017156 208.181.209.61 (Fri, 08 Jun 2001 09:19:16 PDT) NNTP-Posting-Date: Fri, 08 Jun 2001 09:19:16 PDT Xref: archiver1.google.com comp.lang.ruby:10502 comp.lang.ada:8430 comp.lang.awk:2916 comp.lang.clarion:21465 comp.lang.java.programmer:74827 comp.lang.pl1:922 comp.lang.vrml:3661 Date: 2001-06-08T09:18:25-07:00 List-Id: 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. > > "getZipPlusFive get the US Zip+5 postal code." > > If you add this sort of comment, you just needlessly create typing. > You pad the source, diluting the true information. > > However, if you leave it out entirely, someone just perusing the > JavaDoc instead of the method signatures themselves, is missing vital > information. This works for me: public PostalCode getZipPlusFive(PostalCode zipCode); When perusing java code or its documentation, missing the method signatures themselves seems completely nonsensical to me. Are not the signatures always present even in JavaDoc generated pages? One cannot reliably understand an interface otherwise. > Perhaps then, you could document just the parameter, with no comment. Only if the parameter name and type do not adequately describe themselves. > The problem with this is, how do you tell a "boring" void entry from > one yet to be done? That too could lead to invalid assumptions. My rule is: don't repeat what the code says. This is my canonical bad example: /** * Does a particular thing. * * @parm someInput - some input * @exception InvalidInput raised when the input is invalid * @return the result */ public Result doParticularThing(Input someInput) throws InvalidInput this is ok: public Result doParticularThing(Input someInput) throws InvalidInput this is too: /** * @exception InvalidInput when someInput is null or not blah blah * @return a valid result or null when blah blah */ public Result doParticularThing(Input someInput) throws InvalidInput That is, comments describe things not intuitively available from the code. -- Cheers, The Rhythm is around me, The Rhythm has control. Ray Blaak The Rhythm is inside me, blaak@infomatch.com The Rhythm has my soul.