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

[Antoine Pitrou]

On Sat, 18 May 2013 23:41:59 -0700
Raymond Hettinger <raymond.hettinger at gmail.com> wrote:
> 
> We should continue to encourage users to make thorough unit tests
> and to leave doctests for documentation.  That said, it should be
> recognized that some testing is better than no testing.  And doctests
> may be attractive in that regard because it is almost effortless to
> cut-and-paste a snippet from the interactive prompt.  That isn't a
> best practice, but it isn't a worst practice either.

There are other reasons to hate doctest, such as the obnoxious
error reporting.  Having to wade through ten pages of output to find
what went wrong is no fun.

Also the difficulty of editing them. For some reason, my editor doesn't
offer me facilities to edit interactive prompt session snippets.

All in all, I try hard to ignore any doctest present in the Python test
suite.

Regards

Antoine.