Re: Commenting code

[Charles Hixson <charleshixsn@earthlink.net>]

Roedy Green wrote:

> On Thu, 14 Jun 2001 14:20:50 -0500, "Conrad Schneiker"
> <schneiker@jump.net> 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/