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

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


From   Richard Williams <[email protected]>
To   [email protected]
Subject   Re: st: Documenting ssc contributions: efficiency for Man and machine
Date   Mon, 19 Jan 2004 11:15:23 -0500

At 03:05 PM 1/19/2004 +0000, Allan Reese wrote:
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.
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.

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
FAX: (574)288-4373
HOME: (574)289-5227
EMAIL: [email protected]
WWW (personal): http://www.nd.edu/~rwilliam
WWW (department): http://www.nd.edu/~soc


*
* 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