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

[Mark Janssen]

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