[Python-Dev] Unit testing (again)

[Tim Peters]

[Michel Pelletier]
> ...
> A personal issue for me is that it overloads the docstring, no
> biggy, but it's just a personal nit I don't particularly like about
> doctest.

No.  The docstring remains documentation.  But documentation without
examples generally sucks, due to the limitations of English in being
precise.  A sharp example can be worth 1,000 words.  doctest is being used
as *intended* to the extent that the embedded examples are helpful for
documentation purposes.  doctest then guarantees the examples continue to
work exactly as advertised over time (and they don't!  examples *always* get
out of date, but without (something like) doctest they never get repaired).
As I suggested at the start, read the docstrings for difflib.py:  the
examples are an integral part of the docs, and you shouldn't get any sense
that they're there "just for testing" (if you do, the examples are poorly
chosen, or poorly motivated in the surrounding commentary).

Beyond that, doctest will also execute any code it finds in the
module.__test__ dict, which maps arbitrary names to arbitrary strings.
Anyone using doctest primarily as a testing framework should stuff their
test strings into __test__ and leave the docstrings alone.

> Another issue is documentation.  I don't know how much documentation
> doctest has,

Look at its docstrings -- they not only explain it in detail, but contain
examples of use that doctest can check <wink>.