On 22 February 2010 20:40, Julian Edwards <[email protected]> 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/> _______________________________________________ Mailing list: https://launchpad.net/~launchpad-dev Post to : [email protected] Unsubscribe : https://launchpad.net/~launchpad-dev More help : https://help.launchpad.net/ListHelp
