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

[Chris Withers]

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

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

> I like putting moderate amount of test
> code in the implementation. 

how about putting lots of tests in a test package in the implementation package? ;-)

> I fine that that helps to document
> the implementation and it helps me make sure that all of the implementation
> is tested.

Wasn't there a tool to check which source lines where checked?
(I might just be dreaming of that though ;-)

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

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

Indeed.

> 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

> Doctest also encourages documentation and,

...as much as # encourages commenting ;-)

> because of the executable
> examples, encourages keeping the documentation consistent with the code.

Fair point :-)

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

:'(

Chris

-- 
Simplistix - Content Management, Zope & Python Consulting
            - http://www.simplistix.co.uk