GNU Info

(python2.1-lib.info)Soapbox

---

Prev: Warnings Up: doctest

---

Enter node , (file) or (file)node

Soapbox
-------

The first word in doctest is "doc", and that's why the author wrote
doctest:  to keep documentation up to date.  It so happens that doctest
makes a pleasant unit testing environment, but that's not its primary
purpose.

Choose docstring examples with care.  There's an art to this that needs
to be learned -- it may not be natural at first.  Examples should add
genuine value to the documentation.  A good example can often be worth
many words.  If possible, show just a few normal cases, show endcases,
show interesting subtle cases, and show an example of each kind of
exception that can be raised.  You're probably testing for endcases and
subtle cases anyway in an interactive shell:  doctest wants to make it
as easy as possible to capture those sessions, and will verify they
continue to work as designed forever after.

If done with care, the examples will be invaluable for your users, and
will pay back the time it takes to collect them many times over as the
years go by and "things change".  I'm still amazed at how often one of
my doctest examples stops working after a "harmless" change.

For exhaustive testing, or testing boring cases that add no value to the
docs, define a `__test__' dict instead.  That's what it's for.