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

Barry Warsaw barry at python.org
Tue May 21 00:48:32 CEST 2013

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

More information about the Python-Dev mailing list