Re: RFC: Proposed new style for documenting and testing ZTK packages
Jonathan Lange <[email protected]>
| Newsgroups | gmane.comp.web.zope.devel |
|---|---|
| Message-ID | <[email protected]> |
On Mon, Apr 19, 2010 at 6:42 PM, Marius Gedminas <[email protected]> wrote: > On Mon, Apr 19, 2010 at 03:56:02PM +0200, Wichert Akkerman wrote: >> On 4/19/10 15:48 , Marius Gedminas wrote: >> > def doctest_MyClass_bar(): >> > """Test MyClass.bar >> > >> > >>> y = MyClass() >> > >> > The bar method peforms a bar calculation that typically returns >> > twenty-three: >> > >> > >>> y.bar() >> > 23 >> > >> > """ >> >> What is the advantage of that over: >> >> def test_something(self): >> # Test MyClass.bar >> >> y=MyClass() > > *cringe* > > Sorry, I've this reflex to cringe every time I see a PEP-8 violation. > >> >> # The bar method peforms a bar calculation that typically >> # returns 23. >> >> self.assertEqual(y.bar(), 23) >> >> It reads the same, and as a bonus you can step through it with pdb and >> syntax highlighting works normally in most editors. > > The "advantage" is that I've rarely seen comments in unit tests and > personally I never felt compelled to write a comment when writing a unit > test. > Twisted and Launchpad both have policies that require new or modified unit tests to have comments, enforced as a part of our respective review processes. This seems to work well, since the reviewer can block silly comments. The documentation you get is more like a list of requirements / behaviours (e.g. "We raise an error when we try to create a branch in a namespace where there is already a branch of the same name") than a story, but sometimes that's a good thing. It's surprising how easy it is to slip into the habit. It's no substitute for tutorial / howto documentation, but is often a great supplement to API docs. jml _______________________________________________ Zope-Dev maillist - [email protected] https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )