[Zope3-dev] Re: [Zope-Checkins] CVS: Zope3/src/persistent/tests - test_persistent.py:1.5 persistent.txt:1.2

[Jim Fulton]

Chris Withers wrote:
> Jim Fulton wrote:
> 
>>> Feed the text of a doctest to python and I'm sure it will complain ;-)
>>
>>
>> No, Python handles the example just fine.
> 
> 
> Hmm.. can you point me to a good example of a doctest so I can show you 
> what I mean?

There are now tests all over the place.  Jeremy's checkin that started this
thread is a good one: src/persistent/tests/persistent.txt.

In the future, I'd like to have a lot more README.txt files explaining
packages and having executable examples.

src/zope/configuration/config.py has lots of examples of tests in
implementation doc strings.  I like putting moderate amount of test
code in the implementation.  I fine that that helps to document
the implementation and it helps me make sure that all of the implementation
is tested.

src/zope/configuration/tests/test_simple.py is an example of test file
as documentation. This is the sort of thing that is better handled as
separate .txt files.




>>> What's wrong with docstrings in unit tests?
>>
>>
>> The docstrings aren't interspuursed with the code.
> 
> 
> If they're not, then the code is too long, or you should be adding more 
> python comments to your code...

You can always add comments to your code.  People don't.

doctest encourages (but doesn't guarentee) words by making words
easier to type than code.

Doctest also encourages documentation and, because of the executable
examples, encourages keeping the documentation consistent with the code.

The trend os that we're going to write more and more programmer documentation
as .txt files with execitable examples.  My hope is that some large percentage of
necessary tests will be covered by this.  The left over tests will be for edge cases
or special error conditions.

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