st: rclass AND sclass AND eclass

[Sergiy Radyakin <serjradyakin@gmail.com>]

Dear All,

the documentation for Stata declares that each program can be either
rclass, or sclass, or eclass (or nclass). See -help program-.

In many cases this is indeed true, but as the programs become ever
more complicated, this strict correspondence breaks down at
some level. Here is a trivial demonstration:

program foobar
    foo
    bar
end

program foo, rclass
  return local result = 1
end

program bar, sclass
  sreturn local result = 2
end

Here -foobar- is declared as nclass, and its subroutines are declared
as rclass and sclass. A casual observer might inspect only the
-foobar- main routine, and come to the conclusion that the r- and
s-results are safe and not damaged by the command. While in fact
the program makes use of both r-results and s-results, and hence this
must be clearly documented.

Furthermore, as the calls to subroutines may be contingent on some
run-time conditions, the r-results/s-results may be destroyed
"only sometimes", which makes it hell of a job to debug the program
(especially if you are absolutely confident that -foobar- is an
nclass program :)

The example above is motivated by the real and not too farfetched
standard Stata command -mean-, which saves some of the
[undocumented] results into r-results, but only in verbose mode (does
not save in the quiet mode). Hence two consequences:
1) 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;
2) any program relying on r-results being intact after -mean- is up
for a surprise.

More generally, think of turning your recent do file into an ado file.
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?

Would it make more sense to talk about r-safe (e-safe, s-safe)
commands, in the sense that under no conditions the command will
affect the results saved in the corresponding area?

Alternatively, I see no reason to have rclass, eclass, and sclass as
mutually exclusive. They are each exclusive with nclass by definition,
but not with each other, as I may want to set both r-results and
e-results in the same program. And since I can currently do this in
the
manner illustrated above by introducing technical subroutines of the
proper class, there is no reason to prohibit a command to
set the results of multiple types simultaneously.

Finally, while we generally learn that estimation commands return
their results in e-results, general commands in r-results, and rare
commands return results in s-results, IMHO the documentation would
benefit if the class of the command is spelled clearly right with
the syntax, so that we do not have to scout to "... saves the
following in ...". Should we be optimists and interpret the "...saves
in r()" as
"...saves in r() and leaves e() intact"? or be pessimists and
interpret it as "saves in r() and clears e()"? or most inconveniently
"...saves in r() and may sometimes clear e()"?

I would appreciate if the gurus and novices shared their thoughts on
the above questions.

Thank you very much, Sergiy Radyakin.
*
*   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/