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

Olemis Lang olemis at gmail.com
Wed May 22 06:14:42 CEST 2013

On 5/20/13, Mark Janssen <dreamingforward at gmail.com> wrote:

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

Of course , not , all the opposite . If the approach is understood correctly then the first thing test author will do is to write the code «expected» to get something done . When everything is ok with API code style then write the code . Many problems in the API and inconsistencies are thus detected early . Now all we need is a test() built-in, a companion to help() and we have the primo platform for doctest-code-test cycle for TDD and agile development.

«test() built-in» , "interesting" observation ... at least to me setup.py test is more than enough in real-life , and I guess many people really involved in building APIs for sure will notice that in real life it's not as simple as «doctest-code-test» ; in the same way that TDD is not always exactly like what is read in the books . However writing doctests first for APIs could definitely be helpful to think in advance in terms of the clients , especially when there are some aspects looking a bit fuzzy .

Nevertheless , what is really needed , like I've been saying (elsewhere) since years ago , is a better doctest module . The API in stdlib does not offer the means to really benefit of its potential (<= that does not mean it's bad , it might be better ;) .

Above I was talking about testing libraries defining APIs . In the meantime following the approach sketched above , it's been possible (at least to me) to develop tested & documented RESTful + RPC APIs with relatively little effort .

Besides , the differences between RPC and functions due to subtle technological & implementation details may be erased . Using the approach I've sketched in previous messages it's also possible to run the very same doctests for APIs that are meant to work transparently locally or hosted online (e.g. pastebins ... or other services in the cloud) . The only thing needed is to use the right implementation of doctests setUp / tearDown e.g. switching from Python functions to ServerProxy , or REST , or ...

... so , yes , it's proven to be useful in practice ...

-- Regards,

Olemis.

Apache™ Bloodhound contributor http://issues.apache.org/bloodhound

Blog ES: http://simelo-es.blogspot.com/ Blog EN: http://simelo-en.blogspot.com/

Featured article:

More information about the Python-Dev mailing list