[Zope-dev] RFC: Proposed new style for documenting and testing ZTK packages

[Adam GROSZER]

Hello Tres,

Saturday, April 17, 2010, 3:41:02 AM, you wrote:

TS> -----BEGIN PGP SIGNED MESSAGE-----
TS> Hash: SHA1

<snip>

+lots on more docs
+lots on 100% coverage

TS> The trickier testing bits we would re-write as super thorough, no
TS> shortcuts-taken unit tests:  one testcase class per class (or API
TS> function) under test, at least one method per class-under-test method,
TS> with more preferred to get all code paths / preconditions covered.  The
TS> goal here would be to comment out the doctests from the test_suites and
TS> get the code to 100% coverage using pure unit tests.  Meanwhile, the
TS> doctests would be refactored into the Sphinx documentation, losing all
TS> the bits which obscure their intent as documentation.

I'm somewhat vary on unittests. I've seen some damn cryptic ones that
took a lot of time to decipher.
A doctest somehow forces you to dump your mind (well at least that, if
we're not that brilliant techdoc writers).
OTOH I think most unittests maybe have some comments, worst case they
don't even use "speaking" variable names.
I'm not sure whether we can enforce such rules (super thorough, no
shortcuts-taken, well commented) if we can't easier ones.


-- 
Best regards,
 Adam GROSZER                            mailto:agroszer at gmail.com
--
Quote of the day:
You look tired