[Python-3000] doctests vs. unittests (was Re: pimp; restructuring the standard library)

[Barry Warsaw]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Since this has stopped being on-topic for this mailing list, so just  
one last follow up from me.

On Jun 29, 2007, at 11:37 AM, Phillip J. Eby wrote:

> The question is more one of, "documentation for whom?".  You can  
> write separate documents for library users than for library  
> extenders/developers.  I don't put doctests in docstrings, but if I  
> did, I'd probably only put user doctests there.  As it is, I  
> normally split my doctests into multiple files for different  
> audiences, or under different headings in one large file.
>
> Another library I'm working on has two doctest files for users (a  
> quick intro and a developer guide/reference) and a separate file  
> that tests all the innards.  So, there are a lot of ways to use  
> doctests effectively, at least if you're doing them in text files,  
> rather than in your docstrings.  I've actually never put a doctest  
> in a docstring; it always seems like overkill to me.  (Especially  
> since reST doctests can be made into nice HTML pages like the above!)

I concur with Phillip about two important points.  First, I also  
never put doctests in docstrings.  I find them unreadable, difficult  
to edit, and not conducive to a cohesive narrative.  I always put my  
doctests in a separate file, usually under a 'docs' directory  
actually.  Maybe this will make a difference for people considering  
doctests as a complement to traditional unittests.

Second, I agree that you can achieve a high degree of coverage with  
doctests if you stop to answer Phillip's question: "documentation for  
whom?"  I typically put documentation for users in a separate file  
than documentation for extenders/developers, but that's just personal  
taste.  The important insight is that explaining how to use a library  
often covers most if not all the corner cases of its use.

Lastly, an observation: I've found that using doctests has had the  
surprisingly consequence of making test-driven development  
enjoyable.  I've found myself starting a new task by writing the  
documentation first, which is a great way to design how you want the  
code to work.  Because the documentation is testable, you're left  
with a simple matter of coding <wink> until the doctest passes.

Cheers,
- -Barry

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.7 (Darwin)

iQCVAwUBRoUvbXEjvBPtnXfVAQIodgP9H7+7LFCY+TJtCMbeZjl9Q1JHXBrZyIBj
q0aQFR82qvo/I/OUoAwLAqOQbAxyXXBMiEVuAKBQA8ETCOhmOcF/apTmizu0SWZR
b4a6XbvPiIH9DMeOWyFOEEqchfMYFyqWkp+J5fc1mmyF9wLGeQxdmUffzSy17a66
7b/GQBwajlI=
=Aamm
-----END PGP SIGNATURE-----