Stata The Stata listserver
[Date Prev][Date Next][Thread Prev][Thread Next][Date index][Thread index]

st: RE: Re: Documenting ssc contributions: efficiency for Man and machine


From   "Nick Cox" <[email protected]>
To   <[email protected]>
Subject   st: RE: Re: Documenting ssc contributions: efficiency for Man and machine
Date   Mon, 19 Jan 2004 17:30:39 -0000

This summary from Tom is matched by other commentaries
that concur in broad terms. It also captures my own position. 

I'll just add that explanation (e.g. of formulae, algorithm, 
handling of awkward cases, etc.) intended to be read 
sometimes belongs suitably in the help file. You can 
segregate it as "Remarks" or "Appendix" or whatever
you wish. A help file for a newly written program 
often includes material that might better belong in 
the accompanying STB or SJ write-up; if there never is 
such a write-up, some technicalities can and perhaps should remain 
there for people to read or ignore, especially as many people
will never look at the code. 

Nick 
[email protected] 

> -----Original Message-----
> From: [email protected]
> [mailto:[email protected]]On Behalf Of Steichen
> Sent: 19 January 2004 15:43
> To: [email protected]
> Subject: st: Re: Documenting ssc contributions: efficiency 
> for Man and
> machine
> 
> 
> Allan Reese writes (in part):
> 
> > It was recently reported on this list that Bill Gould 
> thinks that programs
> > should not need comments.
> >
> > I'm on the verge of contributing to SSC, and thought it would be
> > worthwhile packaging two versions of the main routine.
> >
> > One question is whether other people do this, and if there is any
> > convention for the extension code for documented code:
> 
> Bill G. is certainly correct, that the _program_ does not 
> need comments, and
> it is possible that individuals whose full time job is 
> looking at the same
> set of code may not need comments, but I certainly do for 
> my own code and I
> desire comments even more in code written by others.
> 
> I would not wish, though, for a separate version of the 
> .ado merely to
> document the code.  I much prefer judicious comments, 
> interspersed where
> necessary, in the main code. A useful alternative, 
> frequently used by
> StataCorp in its early days and occasionally used by me, is 
> to put extended
> documentation of the program logic in the ado file _after_ the end
> statement. That may slightly slow load time but should not 
> impact on code
> interpretation time.

*
*   For searches and help try:
*   http://www.stata.com/support/faqs/res/findit.html
*   http://www.stata.com/support/statalist/faq
*   http://www.ats.ucla.edu/stat/stata/



© Copyright 1996–2024 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index