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

[Tres Seaver]

-----BEGIN PGP SIGNED MESSAGE-----
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.
- --
===================================================================
Tres Seaver          +1 540-429-0999          tseaver at palladion.com
Palladion Software   "Excellence by Design"    http://palladion.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFH1WRV+gerLs4ltQ4RAqHKAJ4lQgwkiCFIk1YpE6oon+xBbDT0sgCfa2M9
Uer6lWCkZh701UyspIzVso4=
=5qeo
-----END PGP SIGNATURE-----