Depends on what anyone means by "many"...
I find that novices often over-comment, as in
// now find the sum
su `myvar' if `touse', meanonly
local sum = r(sum)
This is an extreme case, but I've seen
similar in real programs. But if someone
finds that useful, so be it.
Official Stata programs tend to have fewer
comments than are often recommended in
elementary programming texts or courses.
That's part of the house style more or less imitated
by most Stata programmers.
I think there are various possible explanations for that:
1. Historically, StataCorp programs were written
by a relatively small number of programmers who
were all very good at writing Stata programs.
They didn't need to explain very much to each
other, or if there was any puzzlement Bill
Gould was just along the corridor to solve
any coding question (or, currently, depending
on the programmer's office, down the stairs,
and then along the corridor). Of course, this
doesn't hold for user-written programs,
especially if the user-programmer has disappeared
from the community.
2. Most statistical programs follow some
relatively simple logic, often just an
expansion of
get the data
do something
put the results
and even on a more detailed level we tend
to follow a small number of well-trodden paths.
Conversely, much Stata trickery (e.g. that with
-by:- or with nested local macro references)
just is too complicated to be explicable by
a comment. It's like any piece of mathematics
that is self-evident when you understand it
and hieroglyphics if you don't: there is not
much middle ground.
I'd not want to argue with anyone who feels they
want to put more comments in their programs
than for example StataCorp programmers typically do.
If lack of comments hinders understanding, then
do add them.
A further point is that a good text editor
offers facilities that help you to see what is
going on. If I wish to understand what a subroutine
does, I just search to see when it is called, etc.
Nick
[email protected]
Richard Williams
> At 04:07 PM 4/13/2005 +0100, Nick Cox wrote:
> >The package -stylerules- on SSC has been
> >updated. I started by making a few changes
> >in the light of Stata 9, but mostly thought
> >of some other things to mention while
> >I was doing that.
>
> "Well-written programs don't need many comments. (Comment: We could
> certainly argue about that!)"
>
> Yes, I might be one of those who quibbles a bit! One thing I find
> confusing is when there are lots of programs in an ado file.
> Going through
> them in isolation can be pretty confusing. Comments like
> "This routine
> does...This routine is called by..." can help a lot. In any event,
> comments don't slow the program down. I might say
> "Well-written programs
> don't need many comments (but go ahead and write them anyway)."
*
* 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/
