The importance of doctests (was Re: [Zope3-dev] Re: First cut at PAS for Zope 3)

[Jim Fulton]

Max M wrote:
> Jim Fulton wrote:
> 
>>   http://svn.zope.org/Zope3/trunk/src/zope/app/pas/README.txt?view=markup
> 
> 
> This doctest based documentation makes it really easy to follow what is 
> going on.

Thanks.

I think this represents a major step forward in the Zope and Python
development process.  It's a lot of work to write clear documentation,
but I think it's worth it.  I want all new Zope 3 modules to be developed
this way.  Not only do you have a valuable artifact at the end, but doing this
excercise helps reasonong about APIs early on.

(Note that I still often prototype before writing doctests. but when I've
reached the point where, based on the prototype, I think I understand
what's going on, I start working on the doctest.  Often, the "final"
API I document in the doctest is different than the one I used when
prototyping.)

Jim

-- 
Jim Fulton           mailto:jim at zope.com       Python Powered!
CTO                  (540) 361-1714            http://www.python.org
Zope Corporation     http://www.zope.com       http://www.zope.org