[TIP] On using doctests all the time WAS: Python Testing book review

[Marius Gedminas]

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
code harder.)

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

Amen to that.

Marius Gedminas
-- 
My inferiority complex isn't as good as yours. 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: Digital signature
URL: <http://lists.idyll.org/pipermail/testing-in-python/attachments/20100314/3ffc6dbd/attachment.pgp>