On Thursday 24 April 2008, Jim Fulton wrote:
> - 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.
I tend to put low level-documentation into text files that have the same name
as the module it is testing. I usually writing for the advanced user or
extension writer target audience. It is usually somewhere in between API and
technical reference documentation. If I can I provide a narrative there too,
though this is usually hard. But at least I am motivating the code and API
(which I think is missing in a lot of the doctests that we have.)
I personally hate these strings in test modules and do not use them.
> - 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.
Why is this not documentation? I think we frequently forget to talk about
different audiences. There is documentation for people wanting to use a
particular module, extend the features or fix problems. In application code,
I write functional tests for the product/project manager and even the end
Web Software Design, Development and Training
Google me. "Zope Stephan Richter"
Zope-Dev maillist - Zope-Dev@zope.org
** No cross posts or HTML encoding! **
(Related lists -