[Zope-dev] Why I dislike narrative doctests

[Jim Fulton]

On Apr 24, 2008, at 1:12 AM, Christian Theune wrote:

> Hi,
>
> On Wed, Apr 23, 2008 at 04:47:59PM -0400, Jim Fulton wrote:
>>
>> On Apr 23, 2008, at 4:47 PM, Marius Gedminas wrote:
>> ...
>>> The point of my message was not to whine
>>> about the state of zope.testing, but to present a new argument  
>>> against
>>> the current fashion of using plain-text narrative doctests for
>>> everything.
>>
>> Except that that is not the current fashion, which has been pointed  
>> out
>> many times in many places.
>
> For my own record (I must have missed this many times in many  
> places), is the
> current fashion something along the lines:
>
> "Use the various test styles as reasonable, text-file narrative  
> doctests are
> preferred."


No.  WRT doc tests:

- If a file is documentation and a test, make sure it is good  
documentation. In that case, documentation comes first. Don't add so  
many tests that it ruins the documentation.

- Test edge cases in separate tests.  These are typically short-ish  
strings in test modules.

- A variation is to have a narrative that doesn't try hard to be  
documentation.  The narrative can be convenient, up to a point, even  
in a test.  These should be clearly marked as not being documentation.

Jim

--
Jim Fulton
Zope Corporation