[Zope-dev] Why I dislike narrative doctests

[Stephan Richter]

On Thursday 24 April 2008, Jim Fulton 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.

I tend to put low level-documentation into text files that have the same name 
as the module it is testing. I usually writing for the advanced user or 
extension writer target audience. It is usually somewhere in between API and 
technical reference documentation. If I can I provide a narrative there too, 
though this is usually hard. But at least I am motivating the code and API 
(which I think is missing in a lot of the doctests that we have.)

I personally hate these strings in test modules and do not use them.

> - 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.

Why is this not documentation? I think we frequently forget to talk about 
different audiences. There is documentation for people wanting to use a 
particular module, extend the features or fix problems. In application code, 
I write functional tests for the product/project manager and even the end 
user.

Regards,
Stephan
-- 
Stephan Richter
Web Software Design, Development and Training
Google me. "Zope Stephan Richter"