[Zope3-dev] The importance of doctests

[Jim Fulton]

The latest version of the tutorial discusses doctests at length:

   http://dev.zope.org/Zope3/programmers_tutorial.pdf

It discusses how to write both unit and functional doctests.

One of the important things about this is that most doctests
should be written as documentation.  When you write new software
components and you need to write tests for the main functionality
of your software you need to:

- Get your head into the mode of writing documentation.
   This is very very very important.

- You need to document how to use the software.  Include examples,
   which are tests.  Include edge-case examples *only* if they don't hurt
   the documentation.  The documentation must be to the user.  For most
   components, the user will be a developer who is using your component.
   For presentation components, the user will be the person using the
   presentation. (In this case, the test will be a functional docest.)

- This documentation should go in a text file.  For programmer
   documentation, typically, you will write a module (a .py file)
   that includes your software. You should write a
   companion text file (a .txt file) that contains the documentation
   for the module.

- Test edge cases in separate Python test files.  These can be traditional
   unit tests or doctests.  In either case, they need to include words that
   describe the edge cases.

For the main (non-edge-case) tests, you need to write them as documentation
first, and as tests second. This is important.

If you don't understand the software you are writing, don't waste time on
documentation or tests; prototype.  But when you reach the point that you
begin to understand what you are writing, then start writing documentation
with examples. Document and test little, then program a little.  I think
you will find, as I have, that the APIs that you document first are cleaner.

Please please please, for new software contributed to Zope 3, follow this
practice. Consider this an edict.

Jim

P.S. (Yes, there are systems, like muti-threaded systems that this
       technique might not work for. These are the exception.)

-- 
Jim Fulton           mailto:jim at zope.com       Python Powered!
CTO                  (540) 361-1714            http://www.python.org
Zope Corporation     http://www.zope.com       http://www.zope.org