kennethreitz/python-for-humans — Issue #2: Instill a resistance to doctest
Author: makuro
Created: 2012-01-09 08:04:33+00:00
State: open

Slide 65 (http://python-for-humans.heroku.com/#65) says that it's a Python best practice to instill a resistance to doctest. I was hoping for clarification as to why this might be. I've listened to the audio, but there's no elaboration there, either.

I remember Nathan Batchelder's criticism in a [post from 2008](http://nedbatchelder.com/blog/200811/things_i_dont_like_about_doctest.html), which also mentions two of Andrew Bennetts posts ([1](http://bemusement.org/diary/2008/October/23/narrative-tests) [2](http://bemusement.org/diary/2008/October/24/more-doctest-problems). But the conclusions ended up being: "doctest can be buggy and ugly, but is still pretty useful provided you use it appropriately." doctest's appropriate use is keeping documentation and functionality in sync. I've found it convenient and useful for both library developers and users when there are working examples in the docs, and doctest really isn't too bad at that.

If you agree, then shouldn't we teach correct use instead of avoidance? If you disagree, I would be eager to learn why.

PS The Issues feature is fun, amirite? :P