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

RE: st: -stylerules- updated on SSC

From   "Nick Cox" <>
To   <>
Subject   RE: st: -stylerules- updated on SSC
Date   Thu, 14 Apr 2005 12:44:11 +0100

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. 


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:

© Copyright 1996–2017 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index