Re: st: rclass AND sclass AND eclass

[daniel klein <klein.daniel.81@googlemail.com>]

Sergiy,

I think you are mixing up programs, ado-files and commands, where
these are different things.

A program is defined as a collection of lines of code, that start with
the -program [define]- statement and end with the -end- statement, as
you can read in [U] 18.1.

An ado-file is a collection of programs (at least one program) as can
be read in [U] 18.11.4. (I agree that this point could be more
stressed in [U] 17)

A command is, in it simplest form, one (built-in) program, but might
as well be an ado-file (i.e. a collection of programs). (This could
also be a little more stressed in [U] 17).

Having defined what we are talking about, I will comment on some of
your statements.

You claim that  "the documentation for Stata declares that each
program can be either rclass, or sclass, or eclass [...] In many cases
this is indeed true, but as the programs become ever more complicated,
this strict correspondence breaks down at some level."

You go on with a demonstartion. Your statement is, however, not true.
The "strict" correspondence _always_ holds. The documentation does
_not_ state, that an ado-file (a collection of programs) can only be
one of  -rclass-, -eclass- or -sclass-, but that a _program_ (as
defined above) can only be one of these classes.

Drawing on your example, program foo is indeed -nclass-. It calls
subprograms, that are -rclass- and -sclass-, but these are programs of
their own, despite the fact that they are all collected in one
(ado)file. So each single one of the three programs in your example is
either -rclass-, -eclass-, or -sclass-, as stated in the
documentation.  The fact that a program calls another program does not
magically transform the calling program into a "multy-class" program.

You go on and ask

"You have probably used dozens of commands each of them affecting
r-results or e-results. How would you title your program -rclass?
eclass? sclass?"

Well, if your  program (as defined above)  does not have a -return-,
-ereturn- or -sreturn- statement, it is -nclass-. It's that simple.

You further mention possible problems, when you say

"any program relying on r-results being intact after -mean- is up for
a surprise."

That is why you should save your results right away, as demonstared in
[U] 18.8. This has the additional advantage of making your code much
easier to read. Asking programmers to document any classes affected by
their ado-files is clearly much more burdensome, than asking the users
to save their results right away. This also applies to the statements
you make in your last paragraph.

Concerning your first point with -mean-

"any program relying on the r-results of mean will [not knowingly]
change its behavior depending on whether it is being executed quietly
or noisily;"

as you state, these results are not documented. Any user who knows
about them, can only do so because she looked into the code. Therfore
she will be aware of the fact, that the reults are only returned if
the program is not run -quitely-. Obviously -mean- is not ment to be
used to obtaion these results in the first place, and that is why I do
not see any need to document them.

I cannot say much about your concern with the exclusivity of -rclass-,
-eclass-, and -sclass- programs but I am quite sure this is not an
arbitrary restriction by Stata Corp. but has something to do with the
underlying C language, where functions are defined.

So, no need for a revolution here.

Best
Daniel
*
*   For searches and help try:
*   http://www.stata.com/help.cgi?search
*   http://www.stata.com/support/statalist/faq
*   http://www.ats.ucla.edu/stat/stata/