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/
