[Python-Dev] Purpose of Doctests [Was: Best practices for Enum] (original) (raw)

Tim Peters tim.peters at gmail.com
Mon May 20 02:28:42 CEST 2013

[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

More information about the Python-Dev mailing list