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: 1073c2,23963231b5359f74 X-Google-Attributes: gid1073c2,public X-Google-Thread: 11440e,23963231b5359f74 X-Google-Attributes: gid11440e,public X-Google-Thread: 10a146,23963231b5359f74 X-Google-Attributes: gid10a146,public X-Google-Thread: 103376,23963231b5359f74 X-Google-Attributes: gid103376,public X-Google-Thread: 101deb,23963231b5359f74 X-Google-Attributes: gid101deb,public X-Google-ArrivalTime: 2001-06-07 14:58:10 PST Path: archiver1.google.com!newsfeed.google.com!sn-xit-02!supernews.com!newsfeed.direct.ca!look.ca!newshub2.rdc1.sfba.home.com!news.home.com!news1.rdc1.bc.home.com.POSTED!not-for-mail From: Roedy Green Newsgroups: comp.lang.ruby,comp.lang.ada,comp.lang.awk,comp.lang.clarion,comp.lang.java.programmer,comp.lang.pl1,comp.lang.vrml Subject: Commenting code Organization: Canadian Mind Products Reply-To: roedy@mindprod.com 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> 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 21:58:10 GMT NNTP-Posting-Host: 24.76.128.193 X-Complaints-To: abuse@home.net X-Trace: news1.rdc1.bc.home.com 991951090 24.76.128.193 (Thu, 07 Jun 2001 14:58:10 PDT) NNTP-Posting-Date: Thu, 07 Jun 2001 14:58:10 PDT Xref: archiver1.google.com comp.lang.ruby:10464 comp.lang.ada:8357 comp.lang.awk:2860 comp.lang.clarion:21359 comp.lang.java.programmer:74523 comp.lang.pl1:867 comp.lang.vrml:3607 Date: 2001-06-07T21:58:10+00:00 List-Id: 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?" So you might create a comment of the form: "getSize gets the number of elements currently in the collection, not counting free slots." however, sometimes there is nothing really useful you could add: e.g. "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. Perhaps then, you could document just the parameter, with no comment. 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 long term solution is to use SCIDS, where code and the equivalent of JavaDoc are much more rigidly intertwined. There would be not need to type or see any unwanted bubblegum filler, and there would be a distinction between a entry that does not need a comment and one that does not yet have a comment. You could also encode your comments by their surprise value. That way for most of the time, you would see only the most important comments, and gradually fill in picky detail only when you were having a problem. Assembler commenting requires that you be able to follow the logic without looking at ANY of the code. Without a complete picture of what is going on in the comments, it is very difficult to find the code you are looking for. With well-named methods you don't need to do this for high level languages. 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.