[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:
> 
>>> 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.
> 
> 
> Right, but:
> 
> python persistent.txt won't help me much, and I don't know of an emacs 
> mode for the kind of pseudo source code

It's not pseudo code.

 > you have interspersed in that
> file...
> 
>> In the future, I'd like to have a lot more README.txt files explaining
>> packages and having executable examples.
> 
> 
> How would a user execute these examples?

See Jeremy's response.

>> src/zope/configuration/config.py has lots of examples of tests in
>> implementation doc strings.  
> 
> 
> These appear to just bloat the code and make it harder to find the 
> "there, there", to use an SarnaEbyism... or is that just me?

It's a matter of taste.  Comments bloat code too.  I like having the
examples close by.

...


>> 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.
> 
> 
> Yeah, that's quite a commical start to the file...

Commical? How so?


>> doctest encourages (but doesn't guarentee) words by making words
>> easier to type than code.
> 
> 
> Urm? Adding a comment has gotta be easier than writing all those >>>, 
> and ...'s

Right....what's your point?

In doctests, words are much easier to type than code.

In traditional tests, words are harder to write than code.
That's *my* point.


>> Doctest also encourages documentation and,
> 
> 
> ...as much as # encourages commenting ;-)

# discourages commenting.

It makes it harder to wite words.

OTOH, doctest encouraging writing documentation because:

- It makes sure the documentation stays consistent with the
   implementation.

- For some of your tests, it allows you to kill to birds with
   one stone.  You have to write tests anyway. It's less work,
   in my experience, to write them as documentation.


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