[Zope-dev] Why I dislike narrative doctests

[Jim Fulton]

On Apr 25, 2008, at 1:59 AM, Lennart Regebro wrote:

> On Thu, Apr 24, 2008 at 10:07 PM, Jim Fulton <jim at zope.com> wrote:
>> - 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.
>
> I'ö happy to here this from an authorative source. I've been saying it
> for years, and I have usually been contradicted by people saying "no
> all tests should be doctests", Lets kill that sillyness once and for
> all now. :-)


Everything I said above refers to doctests.

I only pointed out that long narrative doctests aren't always desirable.

Having said that, I can live with regular unit tests that are easy to  
follow and documented.

Jim

--
Jim Fulton
Zope Corporation