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

[Jonathan Lange]

On Mon, Apr 19, 2010 at 6:42 PM, Marius Gedminas <marius at gedmin.as> 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