Re: [Zope3-Users] Re: [Zope] Debugging doctests
On Feb 23, 2006, at 1:57 PM, Benji York wrote:
But it's of course a judgment call.
Perhaps this is just one of those to-each-his-own things. <shrug> My own are doctests. ;)
Sure. I actually really appreciate reading good doctests, they help a lot, and they beat not having any docs at all any day! A non-sequitur: For truly standalone packages, I suspect that people expect some form of non-executable narrative documentation to be included that ties the continued use of the package together with its implementation. In my experience, it's easy to get lured into thinking that you've documented a package properly because it has doctests and interface documentation, when in reality it probably needs some other form of documentation beyond the doctests (e.g. high- level overview of purpose, how to install it, what other packages it depends upon, which versions of Python/Zope it works with, who is responsible for maintaining the package, where to report bugs, and so on). I suppose this is really a packaging issue, but it would be nice if more packages in the zope namespace package were treated as "islands" like this that could be installed separately from Zope proper. It would also likely help prevent inappropriate dependencies from creeping in. Zope 2 wasn't born a mess of spaghetti dependencies, they just sort of grew like weeds over time. - C
On Thursday 23 February 2006 14:16, Chris McDonough wrote:
(e.g. high- level overview of purpose, how to install it, what other packages it depends upon, which versions of Python/Zope it works with, who is responsible for maintaining the package, where to report bugs, and so on). I suppose this is really a packaging issue, but it would be nice if more packages in the zope namespace package were treated as "islands" like this that could be installed separately from Zope proper.
The ZSCP tries to exactly capture this information and provide it via its site. So, I take it that you are a second voter in favor of not requiring all tests to be doctests. Regards, Stephan -- Stephan Richter CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student) Web2k - Web Software Design, Development and Training
On Feb 23, 2006, at 4:51 PM, Stephan Richter wrote:
So, I take it that you are a second voter in favor of not requiring all tests to be doctests.
If the ZSCP thing takes off, I think test/doc req'ts should be somewhat looser than mandating a particular test/doc framework (something along the lines of "must have good test coverage and appropriate narrative documentation", maybe with examples of what this means that could be in doctest format by default). Would that be acceptable? - C
On Thursday 23 February 2006 17:18, Chris McDonough wrote:
On Feb 23, 2006, at 4:51 PM, Stephan Richter wrote:
So, I take it that you are a second voter in favor of not requiring all tests to be doctests.
If the ZSCP thing takes off, I think test/doc req'ts should be somewhat looser than mandating a particular test/doc framework (something along the lines of "must have good test coverage and appropriate narrative documentation", maybe with examples of what this means that could be in doctest format by default). Would that be acceptable?
If there is enough outcry by developers, then yes. ;-) The problem is that it becomes hard to verify that documentation does not deteriorate over time. That means we need certification manager overhead to check that; and it would actually be a difficult task. With doctests I can at least force the developer to update the documentation examples, and if s/he is interested in his package at all, s/he will update the text around it as well. BTW, I have no problem to make the requirements tool independent. I could do the following changes: Doctest-based Testing --> Documentation-based Testing Actually I just did. Maybe I should also change:: Minimal Documentation --> Minimal, Testable Documentation Complete Documentation --> Complete, Testable Documentation Mmmh, now that I look at the matrix, I really think I should have a small explanatory snippet for each metric (below the matrix). Regards, Stephan -- Stephan Richter CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student) Web2k - Web Software Design, Development and Training
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Stephan Richter wrote:
On Thursday 23 February 2006 14:16, Chris McDonough wrote:
(e.g. high- level overview of purpose, how to install it, what other packages it depends upon, which versions of Python/Zope it works with, who is responsible for maintaining the package, where to report bugs, and so on). I suppose this is really a packaging issue, but it would be nice if more packages in the zope namespace package were treated as "islands" like this that could be installed separately from Zope proper.
The ZSCP tries to exactly capture this information and provide it via its site.
So, I take it that you are a second voter in favor of not requiring all tests to be doctests.
Count me as another. Doctests are fine for many cases, but they suck for doing "coverage" / "edge case" testing, which are the "valuable" unit tests for my applications. I would note that the usefulness of a doctest as documentation is inversely proportional to the amount of "setup noise" the test requires. Tres. - -- =================================================================== Tres Seaver +1 202-558-7113 tseaver@palladion.com Palladion Software "Excellence by Design" http://palladion.com -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.1 (GNU/Linux) Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org iD8DBQFD/yhq+gerLs4ltQ4RAk7sAKDILanq+5mbgsq/z0tOHiZpmph1IQCeO+dH Z5ulUBVEml+wxexIwyeF6w0= =anV3 -----END PGP SIGNATURE-----
On 24 Feb 2006, at 16:38, Tres Seaver wrote:
So, I take it that you are a second voter in favor of not requiring all tests to be doctests.
Count me as another. Doctests are fine for many cases, but they suck for doing "coverage" / "edge case" testing, which are the "valuable" unit tests for my applications.
I would note that the usefulness of a doctest as documentation is inversely proportional to the amount of "setup noise" the test requires.
Another argument against the doctest requirement is the fact that you have great packages out there with very extensive "standard" unit tests. Rewriting those to doctests just for this requirement would be asking just a tad too much. jens
participants (4)
-
Chris McDonough -
Jens Vagelpohl -
Stephan Richter -
Tres Seaver