Website hosting service by Active-Venture.com
  

 Back to Index

5.2.8 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.

 

  

 

2002-2004 Active-Venture.com Webhosting Service

 

Disclaimer: This documentation is provided only for the benefits of our hosting customers.
For authoritative source of the documentation, please refer to http://python.org/doc/

 

Domain registration : Buy domain name or register domain name from $5.95/year only

 

Cheap domain registration : Register domain name or buy domain name, including free domain hosting services

 
  Active-Domain.com offers cheap domain registration, domain name transfer and domain search services