On Thu, Jun 17, 2010 at 5:22 AM, Patrick Burns <pburns@pburns.seanet.com>wrote:

> I agree with Hadley, and add that trying
> to have an example be both an example and
> a test may not be good for the example
> aspect either.
>
> Examples should make people who are ignorant
> of the function twig as to how the function
> works.  Creating good examples is hard.
>
> Problems that really test the software are
> unlikely to serve as a good example.  Good
> examples are unlikely to seriously test the
> code.  (But you do want the examples to run,
> it is seriously bad advertising when they
> don't.)
>
> Pat


Creating good examples is hard, but so is creating a research
compendium following the ideas of Reproducible Research of
Donoho and others at Stanford, called Literate Statistical
Practice in the statistical community. The tools are there in
R for this purpose (vignettes, etc.) but they seem to be rarely
used for this purpose.

One reason examples are hard is that they are often isolated
from the research itself, and hard to understand out of context.
The notion of a Research Compendium that includes this
context might help.

But this requires a fair amount of work, and I don't think it is
currently rewarded in the publication process (Journals do not
require it).

The creation of a research compendium can be viewed as
a form of unit testing, and the fact that R has powerful tools
that support this process (Sweave) could be viewed as one of
its outstanding features (relating these comments back to
the topic of this thread).

A list of references on Reproducible Research and LSP
can be found in the package cxxPack. A template for creating
a compendium can also be found there.

Dominick

	[[alternative HTML version deleted]]

