[Date Prev][Date Next][Thread Prev][Thread Next][Date index][Thread index]
Re: st: Documenting ssc contributions: efficiency for Man and machine
At 03:05 PM 1/19/2004 +0000, Allan Reese wrote:
You might try throwing the most monstrous data set you have at your program
and see if the comments really make a significant difference or not. If
they do, then placing the comments just outside the loop might be one way
of addressing the problem.
It was recently reported on this list that Bill Gould thinks that programs
should not need comments. I disagree; it's often hard to remember why a
particular line/variable/condition was needed when reading code written
some months back. Too much computing (eg APL, web-authoring, anything by
** Corp) is write-only code.
On the other hand, for an interpreted language there may be a noticeable
hit on performance if comments are included in, say, an inner loop.
Better still, you might also include a .doc or .pdf file that documents how
the program works; maybe even include some extended examples if you thought
that would be helpful. The Stata reference manual generally does a good
job of not only giving the syntax for a command, but of giving examples of
how it works, when you might want to use it, formulas used, additional
things to read, etc. With a lot of user-written commands, you're pretty
much on your own. Indeed, a user-written routine could well be doing
something wrong, and you wouldn't know it unless you carefully went through
the code or double-checked against another program. At a minimum, it might
be nice to include somewhere in your code or help file a reference to
wherever you got your formulas from.
Richard Williams, Associate Professor
OFFICE: (574)631-6668, (574)631-6463
WWW (personal): http://www.nd.edu/~rwilliam
WWW (department): http://www.nd.edu/~soc
* For searches and help try: