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

Mark Janssen dreamingforward at gmail.com
Mon May 20 19:26:51 CEST 2013

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

+1, very true. I think doctest excel in almost every way above UnitTests. I don't understand the popularity of UnitTests, except perhaps for GUI testing which doctest can't handle. I think people just aren't very imaginative about how to create good doctests that are also good documentation.

That serves two very good purposes in one. How can you beat that? The issues of teardown and setup are fixable and even more beautifully solved with doctests -- just use the lexical scoping of the program to determine the execution environment for the doctests.

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

Cheers,

Mark

More information about the Python-Dev mailing list