[TIP] On using doctests all the time WAS: Python Testing book review
marius at gedmin.as
Sat Mar 13 14:59:15 PST 2010
On Wed, Mar 10, 2010 at 10:33:30AM +1100, Andrew Bennetts wrote:
> Just quickly, because much of this discussion has been had here before:
> Olemis Lang wrote:
> > > I think automatically tested documentation is a wonderful idea.
> > Cool. IMO automatically tested documentation is not just for writing
> > books, but also to document the code ;o)
> Yes, definitely.
> (But tested documentation of the code is unlikely to be a good replacement for a
> typical test suite, as readers of documentation generally don't care about all
> the corner cases your test suite should cover.)
And cramming all (or even just some) of the corner cases into your
documentation is a good way to destroy its readability.
(FWIW I think doctest is not a bad tool for unit tests, if you use it
carefully. For values of "carefully" meaning "don't put your unit tests
into .txt files"; a test_foo.py containing a bunch of empty functions
with docstrings containing tests works much better. You often get tests
that are more readable, at the cost of making refactoring/reuse of test
> > So I use doctest to write my tests 'cause
> > - They are quite readable
> > - ... so even users can read them and use that as a
> > reference, tutorial, ...
> In my experience, tests make poor end-user docs, although it depends a
> little on the sort of user (users of your API vs. of your command line
> etc). I suppose it's better than no docs at all
> Again, tested docs are great, but tests and documentation have different
Amen to that.
My inferiority complex isn't as good as yours.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Size: 197 bytes
Desc: Digital signature
More information about the testing-in-python