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

[Charlie Clark]

Am 19.04.2010, 12:50 Uhr, schrieb Adam GROSZER <agroszer at gmail.com>:

Before I start: + lots on the general idea. Zope's narrative documentation  
is attrocious"[1] and we have lost users and developers as a result.

> I'm somewhat vary on unittests. I've seen some damn cryptic ones that
> took a lot of time to decipher.

All the more reason not to think of them as part of the documentation.  
Would it possible to come up with some metrics for the quality of tests?

> A doctest somehow forces you to dump your mind (well at least that, if
> we're not that brilliant techdoc writers).

Narrative documentation forces you to explain yourself to someone else.  
Neither, however, will necessarily notice if you forget something: tests  
aren't documentation and docu

> OTOH I think most unittests maybe have some comments, worst case they
> don't even use "speaking" variable names.

The key to any of this is making it easy for developers to want to go this  
way. Writing good, legible tests *will* encourage others to emulate them.

> I'm not sure whether we can enforce such rules (super thorough, no
> shortcuts-taken, well commented) if we can't easier ones.

What does Lint have to say about them?

Charlie

[1] http://www.stereoplex.com/2010/jan/14/migrating-django-mingus/
-- 
Charlie Clark
Managing Director
Clark Consulting & Research
German Office
Helmholtzstr. 20
Düsseldorf
D- 40215
Tel: +49-211-600-3657
Mobile: +49-178-782-6226