[Python-Dev] Purpose of Doctests [Was: Best practices for Enum]

[Tim Peters]

[Raymond Hettinger]
> I'm hoping that core developers don't get caught-up in the "doctests are bad
> meme".
>
> Instead, we should be clear about their primary purpose which is to test
> the examples given in docstrings.

I disagree.


>  In many cases, there is a great deal  of benefit to docstrings that have
> worked-out examples (see the docstrings in the decimal module for
> example).  In such cases it is also worthwhile to make sure those examples
> continue to match reality. Doctests are a vehicle for such assurance.

That's representative of how doctest was developed:  to help me in
keeping some well-defined mathematical functions working as intended.
It still excels in that particular area (a few examples to illustrate
normal cases, and a few more to illustrate well-defined end and error
cases - and that's all there _is_ to be tested).


> In other words, doctests have a perfectly legitimate use case.

But more than just one ;-)  Another great use has nothing to do with
docstrings:  using an entire file as "a doctest".   This encourages
writing lots of text explaining what you're doing,. with snippets of
code interspersed to illustrate that the code really does behave in
the ways you've claimed.


> We should continue to encourage users to make thorough unit tests
> and to leave doctests for documentation.

I'd rather encourage users to turn their brains on when writing
doctest files - and when writing unit tests.  I've lost count of how
many times I've seen a unit test fail, then stared helplessly at the
unit test code just trying to figure out what the author thought they
were doing.  A lot of comments in the test code could have helped
that, but - outside of doctest-based tests - there's typically very
little explanatory text in testing code.

picking-your-poison-ly y'rs  - tim