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: 101deb,23963231b5359f74 X-Google-Attributes: gid101deb,public X-Google-Thread: 103376,23963231b5359f74 X-Google-Attributes: gid103376,public X-Google-Thread: 1073c2,23963231b5359f74 X-Google-Attributes: gid1073c2,public X-Google-Thread: 10a146,23963231b5359f74 X-Google-Attributes: gid10a146,public X-Google-Thread: 107a89,23963231b5359f74 X-Google-Attributes: gid107a89,public X-Google-ArrivalTime: 2001-06-15 09:36:17 PST Path: archiver1.google.com!newsfeed.google.com!sn-xit-02!supernews.com!newsfeed.direct.ca!look.ca!newsfeed1.earthlink.net!newsfeed.earthlink.net!newsmaster1.prod.itd.earthlink.net!newsread2.prod.itd.earthlink.net.POSTED!not-for-mail Message-ID: <3B2A3975.7040408@earthlink.net> From: Charles Hixson User-Agent: Mozilla/5.0 (Windows; U; Win95; en-US; rv:0.9.1) Gecko/20010607 X-Accept-Language: en-us MIME-Version: 1.0 Newsgroups: comp.lang.ada,comp.lang.awk,comp.lang.clarion,comp.lang.java.programmer,comp.lang.pl1,comp.lang.vrml Subject: Re: Commenting code References: <3B1E1452.BAFAAB7F@baesystems.com> <3B1E4B93.7FB8A94D@lmtas.lmco.com> <3B1F3704.C7E0D03A@brighton.ac.uk> <3b20d633$8$fuzhry$mr2ice@va.news.verio.net> <3B20EDAC.5A4F7BD4@home.com> <3b27569c$1$fuzhry$mr2ice@va.news.verio.net> <3B27AD17.DF50BDED@home.com> <3b28b178$7$fuzhry$mr2ice@va.news.verio.net> <3B28E4BA.551784C1@home.com> <9gb2ti$p2q$1@news.jump.net> <0rbiito3r5sf40n19n3dklasqrf40r6u0h@4ax.com> Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit Date: Fri, 15 Jun 2001 16:36:16 GMT NNTP-Posting-Host: 198.94.156.19 X-Complaints-To: abuse@earthlink.net X-Trace: newsread2.prod.itd.earthlink.net 992622976 198.94.156.19 (Fri, 15 Jun 2001 09:36:16 PDT) NNTP-Posting-Date: Fri, 15 Jun 2001 09:36:16 PDT Organization: EarthLink Inc. -- http://www.EarthLink.net X-Received-Date: Fri, 15 Jun 2001 09:34:10 PDT (newsmaster1.prod.itd.earthlink.net) Xref: archiver1.google.com comp.lang.ada:8783 comp.lang.awk:3073 comp.lang.clarion:22049 comp.lang.java.programmer:76707 comp.lang.pl1:1049 comp.lang.vrml:3827 Date: 2001-06-15T16:36:16+00:00 List-Id: Roedy Green wrote: > On Thu, 14 Jun 2001 14:20:50 -0500, "Conrad Schneiker" > wrote or quoted : > > >>IMHO, this has strayed pretty far off topic insofar as Ruby is concerned >> > > I don't know what Ruby even is, but if it is some sort of computer > language, why would it be unique in all computer languages? All other > languages seem to require very much the same sort of commenting > etiquette. > > > For more detail, please look up the key words mentioned in this post in > the Java Glossary at: http://mindprod.com/gloss.html > > -- > Roedy Green, Canadian Mind Products > Custom computer programming since 1963. Ready to take on new work. > Actually, different languages have differing needs depending on their features. Javadoc says certain things about how Java should be commented. Python's documentation strings imply something a bit different. Eiffel is vastly different because they use the short tool as a primary means of documentation. Ada considers that most of the user documentation should be in the *.ads file, where details of the program operation should be in the *.adb file. C/C++ is generally free-form and totally anarchic, unless you are using one of the documentation tools. Smalltalk believes that you should be able to obtain most of the information via direct inspection of the code ... but there is a line or two at the beginning of each method that is traditionally for comments about things that aren't obvious. Etc. That's most of the languages that I know well enough to comment on, and no two of them are really closely related to each other in what a comment should be or how it should be done. About all that they all agree on it that you shouldn't document totally obvious things, and you should document obscure things somewhere. But they sure don't agree on who should see that latter documentation. -- Charles Hixson Copy software legally, the GNU way! Use GNU software, and legally make and share copies of software. See http://www.gnu.org http://www.redhat.com http://www.linux-mandrake.com http://www.calderasystems.com/ http://www.linuxapps.com/