[TIP] Docstrings in Test methods

[Ned Batchelder]

On 11/5/2011 9:05 AM, Mike Pirnat wrote:
> I work in a pretty big codebase with a lot of developers.  We prefer
> not having a docstring on our tests so that when they do fail, we can
> quickly identify what test it is (and who the best people to fix it
> are going to be).
>
> Our compromise in the sake of explaining a test is to use a comment
> where we would otherwise have a docstring in production code.
>
> I would be all for using docstrings for consistency with our
> production code if the test runner wouldn't replace the test
> module/class/method with the docstring in its output.
>
I completely agree.  I use comments in test methods rather than docstrings.

BTW: the line from my slides was about product code, not test code:  
Sometimes a real stumbling block to testing is that you have to decide 
what your product code actually does.  Once you figure that out, it's a 
good idea to write it down in the docstrings.

--Ned.