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.
Tom Steichen
*
* 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/
