[Zope-dev] RFC: Proposed new style for documenting and testing ZTK packages

[Marius Gedminas]

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.

A doctest without any text preceding a >>> line feels Wrong(TM) to me,
and, judging from our test suite, the other programmers on my team.

Whether that advantage is worth the multitude of disadvantages of
doctest-for-unit-testing is a different question.  Over the years my
opinion slowly changed from "probably" to "rarely".

Marius Gedminas
-- 
http://pov.lt/ -- Zope 3 consulting and development
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: Digital signature
Url : http://mail.zope.org/pipermail/zope-dev/attachments/20100419/f72ccde3/attachment.bin