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

[Barry Warsaw]

I don't think a python-dev discussion about the value of doctests is going to
change minds one way or the other, but I just *had* to respond to this one
point:

On May 20, 2013, at 11:26 PM, Michael Foord wrote:

>* Doctests practically beg you to write your code first and then copy and
>* paste terminal sessions - they're the enemy of TDD

In a sense, they're your best friend too.

Countless times, when I'm designing an API, writing the documentation first
helps clarify how I want the library to work, or where I need to think about
the API more deeply.  In much the same way that TDD is ideal when you know
what you're aiming for, when you *don't* exactly know, it's a huge benefit to
write the documentation first.  Doing so will bring into stark contrast what
needs improvement in your API.

The fact that you can then test much of this documentation as you go, brings
the win of TDD to your documentation.

-Barry