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
_______________________________________________
Zope-Dev maillist  -  Zope-Dev@zope.org
http://mail.zope.org/mailman/listinfo/zope-dev
**  No cross posts or HTML encoding!  **
(Related lists - http://mail.zope.org/mailman/listinfo/zope-announce
http://mail.zope.org/mailman/listinfo/zope )

Reply via email to