launchpad-dev team mailing list archive

[Martin Pool <mbp@xxxxxxxxxxxxx>]

On 22 February 2010 20:40, Julian Edwards <julian.edwards@xxxxxxxxxxxxx> wrote:
>> imo you are either writing doc tests or you're writing testable
>> documentation; they are not the same thing at all and it's hard to
>> make one document work for both.
>
> I have exactly the opposite opinion :)
>
> I'd like to see an example of why you think it's hard though?

A good test suite should exercise every distinct domain of the
interface, trying to break it, paying attention to edge cases.  You
expect them to all fail at least once so it's good to make them pretty
fine grained and perhaps to use validating decorators or something
else that will check internals or be faster, and perhaps to use
infrastructure to apply the same test in many different situations.
Having the output from one test feed into the next is generally poor
because you get cascading confusion.

Whereas for documentation you want someone to be able to read it from
start to end, which means it should have a kind of narrative, show the
typical cases, not the obscure ones, and showing the typical way to
use the object, not a special setup for testing.

At least that's how it seems to me.  If you have an example of a
something that works really well for both at once I would be happy to
see it.

-- 
Martin <http://launchpad.net/~mbp/>