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

[Christian Theune]

On 04/19/2010 03:56 PM, 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()
>
>            # 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.

I had some good experiences in the last 6 months or so when switching 
from doctests that were tests (not documentation) to this style of testing.

Also the review process mentioned (or pairing) helps to put comments in 
places where the code isn't easily understood by itself (after that, 
refactor the code so you don't need comments and put the real comments in).

Christian

-- 
Christian Theune · ct at gocept.com
gocept gmbh & co. kg · forsterstraße 29 · 06112 halle (saale) · germany
http://gocept.com · tel +49 345 1229889 0 · fax +49 345 1229889 1
Zope and Plone consulting and development