Joseph Coveney started a thread to which others
have contributed comments and suggestions. The
underlying issue is making it easy as possible
for people to find user-written programs
in particular areas.
I am happy to have been associated by Fred Wolfe with
the notion that .ado files should be matched by
.hlp files. This is, however, hardly my
idea, as it has been a Stata standard since the
earliest days.
More generally, I find myself reluctant to sign
up to any movement to start suggesting yet more
standards for programmers.
I think we need first to distinguish
various levels at which users may contribute:
1. Code that becomes part of official Stata,
in which case StataCorp standards of code
and documentation are the issue.
Note that for the most part those standards
are evident and accessible for users to follow:
in the manual, in -examplehelpfile.hlp-,
in the code itself, etc.
2. Code that is published in the Stata Journal,
in which case a review process is involved. We
have rejected submissions in the past on the
grounds that the software was not good enough,
and we do what we can to improve code submissions,
as some members of Statalist will know.
We can't claim that all contributions match
the standard of 1. I'd like to think that
was our goal. [We == the Editors of the SJ,
Joe Newton and myself.]
3. Code distributed via SSC in which case there
are some minimum criteria now for acceptance
and maintenance in the archive. For example,
there must be a help file. But code on SSC
is _not_ necessarily reviewed by anyone.
4. Code published by individuals on their
own sites, in which case their own criteria apply.
(I'd guess that on average the standard was
no different from that of 3.)
5. Code "published", or at least made available,
in other ways, often with a rider "This is rough/
incomplete/poorly documented/undocumented, but
if it is of use of you, I am happy!". Code
or code fragments published via Statalist postings
are one example.
Now at this point some readers may already find
this range confusing. The main point so far
is that given a great range of publication
outlets and styles, there is already diversity,
and there are already various standards, or none. I'm not
clear that we need yet more standards, especially
because the likelihood of them being followed
seems pretty low. (As the late Frank Anscombe pointed
out, one key principle about standards is that
you should follow mine.)
Fred Wolfe made an interesting point, that
programs can contain their own comments and
even their own documentation. And many programmers,
including myself, both do this themselves and
know that looking at the code can be interesting
and instructive. (Sometimes the code is where
the undocumented options are documented!)
But this is not much of a solution for the people
who are most confused. In practice they are
the least likely people to be able to
find where a program is installed, and to
fire up their favourite text editor to look
at the code. And why should they? By intention
or by design I have shown many people locally
the fact that Stata ados are just text files
that can be looked at, but I have influenced
very few to follow suit, and that's not
surprising really. It can take another
programmer to find a bug, or even a feature.
And I think it's a poor solution in any case.
Comments that I write are private, although
not secret: they are for myself when revisiting
the code, and for any other programmers who
want to examine the code. They are _not_ public
comments that all users are supposed to read! That
is, emphatically, the role of the help file.
If Fred, or any other programmer, can dispense
with a help file, so be it, but that is not
an acceptable standard to follow.
Finally, I see emphasis on the onus for
programmers to make their work even more
findable and on StataCorp to tweak -search-/
-net search-/-findit-. I'd like to see more
emphasis on the need for people to do some
of the work for themselves when they look
for things. We already have a Statalist
subculture that thinks that Statalist is
a substitute for reading the help, the manual,
and the literature first. We already have users
to seem to think that help files should explain
techniques. I'm sorry that
-todate- is not tremendously visible, but
it's not alone in that the name is not
obvious until you know what it is and the keywords
are shared with much other stuff.
Positively, here are some of the things
people can do:
1. Keep a notebook, computer file, even
a Stata data file with your own program
names, favourite user programs, etc. Only
you can optimise for your own mix of interests
and experience.
2. You can get a text file with all SSC stuff
in the following way:
log using sscprograms.log
set more off
foreach l in `c(alpha)' _ {
ssc desc `l'
}
set more on
log close
Now you have something you can edit
or skim or search.
3. If users want their code to be more
visible, they should consider publishing
in the SJ or via SSC. SSC does not contain
official code, but the -ssc- handles make
archived material especially visible and
manageable.
Nick
[email protected]
*
* 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/
