From: ara.t.howard@...
Date: 2006-01-13T05:30:26+09:00
Subject: Re: Design contracts and refactoring (was Re: mathn: ugly warnings)

On Fri, 13 Jan 2006, Mathieu Bouchard wrote:

> I've thought of a triad:
>
>  A. "the real thing"
>  B. what it's documented as
>  C. a way to verify that (1) and (2) agree

i did something recently that addresses this in a way:

first of all, included no docs - only tests and a samples/ dir.  the samples
dir has very simple programs in it like a.rb, b.rb, etc.  every sample program
outputs yaml, which is quite nice to read.  in addition, i store the expected
output of each sample program in sample/expected/a.rb.  now it's quite simple
for my unit tests to also check that every sample program runs and creates the
correct output.

admittedly this is only a step up from saying 'read the unit test', but the
higher level and shortness of sample programs does make it a step up.  also,
the sample programs can progress in complexity in such a way to teach the user
in a nice way.

-a
-- 
strong and healthy, who thinks of sickness until it strikes like lightning?
preoccupied with the world, who thinks of death, until it arrives like
thunder?  -- milarepa