On Thu, Apr 24, 2008 at 3:07 PM, Jim Fulton <jim@zope.com> wrote:
On Apr 24, 2008, at 1:12 AM, Christian Theune wrote:
Hi,
On Wed, Apr 23, 2008 at 04:47:59PM -0400, Jim Fulton wrote:
On Apr 23, 2008, at 4:47 PM, Marius Gedminas wrote: ...
The point of my message was not to whine about the state of zope.testing, but to present a new argument against the current fashion of using plain-text narrative doctests for everything.
Except that that is not the current fashion, which has been pointed out many times in many places.
For my own record (I must have missed this many times in many places), is the current fashion something along the lines:
"Use the various test styles as reasonable, text-file narrative doctests are preferred."
No. WRT doc tests:
- If a file is documentation and a test, make sure it is good documentation. In that case, documentation comes first. Don't add so many tests that it ruins the documentation.
- Test edge cases in separate tests. These are typically short-ish strings in test modules.
- A variation is to have a narrative that doesn't try hard to be documentation. The narrative can be convenient, up to a point, even in a test. These should be clearly marked as not being documentation.
However, as Sphinx lowers the barrier to cross-referencing, they will become important as link destinations from 'real' documentation.
Jim
-- Jim Fulton Zope Corporation
_______________________________________________
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 )