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 user. Regards, Stephan -- Stephan Richter Web Software Design, Development and Training Google me. "Zope Stephan Richter"