[TIP] doctest and floats

[Andrew Bennetts]

Noah Gift wrote:
> All of this brings up an interesting question about doctests, which I  
> happen to prefer to unittests btw. If you write a doctest, and "fake  
> it out" to accurately test your code, which is worse, an inaccurate  
> doctest, which can be interpreted as documentation, or an incompletely  
> tested module?  This has been a dilemma for me in some situations,  
> although I probably don't know all of the doctest tricks yet.

Decide on what you're writing.  If you're writing documentation, make it good
documentation.  If you're writing tests to make sure your code works, make it
test comprehensively and accurately.

These can be conflicting goals.  I don't believe it is always possible for great
tests to be great documentation.  For example, for a user of an API, ideally
corner cases should Just Work and thus need no documentation, but for a
maintainer having tests covering those corner cases is vital.

So the question might be which is the worse trade-off: having tests and
documentation combined in a file that does a poor job of satisfying both needs,
or having two files?

This is not to say your tests cannot all be in doctest format (although that is
not my preference), just that sometimes you really do need separate “doc/” and
“tests/” directories.  

-Andrew.