Hash: SHA1

Gary Poster wrote:
> I did a five-minute skim of the checkin but hope to look a bit more  
> tomorrow.  Hopefully Marius, Benji, Albertas, or someone else who has  
> actually done work on this package will take a look and chime in.
> I did have one somewhat trivial thought.  I generally prefer durations  
> and intervals expressed as datetime.timedeltas myself, because they  
> convey their meaning without having to look it up docs (is that number  
> value a number of seconds?  milliseconds?  minutes?).  There might  
> even be a zcml built in for schema field for that; I believe I  
> remember that there is in ZConfig.
> Also, some variety of doctest would be nice.  Even when a package is  
> not using doctests, I add new tests as doctest unless there's a really  
> good reason not to.

Becuase they make for poor unit tests?  Using them to document the
"mainline" use cases for an API is one thing:  using them to do thorough
coverage of edge cases is quite another. I find that for the latter,
they fail *both* as documentation *and* as tests:  their value as
documentation drops as the amount of scaffoldiing rises, and the lack of
isolation between tests sharply reduces their value for testing the corners.

I realize I have said this before, but then others keep urging the
"doctests everywhere" meme.

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

- --
Tres Seaver          +1 540-429-0999          [EMAIL PROTECTED]
Palladion Software   "Excellence by Design"    http://palladion.com
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org


Zope-Dev maillist  -  Zope-Dev@zope.org
**  No cross posts or HTML encoding!  **
(Related lists - 
 http://mail.zope.org/mailman/listinfo/zope )

Reply via email to