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

[Olemis Lang]

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: