[Zope-dev] Re: zope.sendmail Retry fixes and new state machine.

[Gary Poster]

On Mar 10, 2008, at 12:39 PM, Tres Seaver wrote:

> Gary Poster wrote:

[...]

Doctest/unittest holy war: bah.  I've heard the arguments, I don't see  
either side as perfect, and I've made my choice.  I'm very fine with  
others having different opinions and choices.

As Benji said, the doctest choice has been made for the zope.* tree,  
so, until the current choice changes, it's reasonable to encourage  
doctests for zope.sendmail.  If folks want to agitate for more unit  
tests in zope.*, have at it, but that doesn't change where we are now.

BTW, Wichert, trying to be helpful: if you do have to deal with  
someone else's doctests, you can in fact use pdb.  Just put the  
set_trace() on the same line as the command you want to step into.   
You can't step into subsequent doctest lines, but that does not tend  
to cause me too many problems, IME.  Maybe that's your complaint,  
though.

(To be clear, Wichert, I grant the validity of other points you and  
Tres and others made.  There are counter-arguments, and matters of  
taste.  Other folks can argue about this, not me.)

>> In this case, it looks like you've made the code significantly more
>> robust, which has added some probably necessary complexity.  The code
>> looks readable, but I recommend a maintainer-oriented overview/
>> introduction as a doctest, at the least.  For instance, perhaps you
>> could think about documentation about the rationale for the approach
>> and about the dance that this code participates in (with the lock
>> files and all the possible SMTP error conditions and the code's
>> responses).  Of course, even more friendly docs than that would be
>> nice, but I'm only asking for what I myself tend to give,  
>> unfortunately.
>
> I would also value such documntation, but doubt that the scaffolding
> necessary to make the doctest part of the dance executable would  
> make it
> any more valuable.


Here's one disagreement I'll bother to stand up for.  Making  
documentation testable does add value to technical docs like this, in  
that it encourages it to stay up-to-date with refactorings.  It is  
certainly not perfect--the examples can be tested but not the  
exposition--but saying that it does not add value in this case seems  
extreme to me.

Perhaps your argument, Tres, is that the effort outweighs the cost in  
this particular case.  That's a more reasonable argument to me.  Maybe  
the scaffolding will be arduous.  However, I would expect that some  
approaches to the doctest scaffolding would in fact mirror the set up  
needed for the unit tests, and I'd encourage Matthew to give it a try  
before immediately giving up.

Gary