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