-----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----- _______________________________________________ Python-3000 mailing list Python-3000@python.org http://mail.python.org/mailman/listinfo/python-3000 Unsubscribe: http://mail.python.org/mailman/options/python-3000/archive%40mail-archive.com
