[Python-Dev] Unit testing (again)

[Guido van Rossum]

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

You're lucky that doctest doesn't return dictionaries!  For functions
that return dictionaries, it's much more natural *for documentation
purposes* to write

  >>> book()
  {'Fred': 'mom', 'Ron': 'Snape'}

than the necessary work-around.  You may deny that's a problem, but
once we've explained dictionaries to our users, we can expect them to
understand that if they see instead

  >>> book()
  {'Ron': 'Snape', 'Fred': 'mom'}

they will understand that that's the same thing.  Writing it this way
is easier to read than

  >>> book() == {'Ron': 'Snape', 'Fred': 'mom'}
  1

I always have to look twice when I see something like that.

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

They are also more voluminous than I'd like the docs for difflib to be...

--Guido van Rossum (home page: http://www.python.org/~guido/)