doctests are a real advantage in Python compared to other languages. The fact that a
text can use code examples that are also runable as tests changes the way TDD can be
done. For instance, part of the documentation can be done through doctests during
the development cycle. This approach also ensures that the provided examples are
up to date and really working.
Building software through doctests rather than regular unit tests is called
Document-Driven Development (DDD). Developers explain what the code is
doing in plain English, while they are implementing it.
Writing a Story
Writing doctests in DDD is done by building a story about how a piece of code
works and should be used. The principles are described in plain English and then a
few code usage examples are distributed throughout the text. A good practice is to
start to write a text on how the code works, and then add some code examples
Let’s look back at the atomisator.parser package doctest. The first version of the
text was:
=================
atomisator.parser
=================
The parser knows how to return a feed content with
a function available as a top-level function.
This function takes the feed url and returns an iterator
on its content. A second parameter can specify how
many entries have to be returned before the iterator is
exhausted. If not given, it is fixed to 10
The example was then completed and the code built with it was:
=================
atomisator.parser
=================
The parser knows how to return a feed content, with
the 'parse' function, available as a top-level function::
>>> from atomisator.parser import parse
