[Python-ideas] Multi-line comment blocks.

Steven D'Aprano steve at pearwood.info
Sat Jun 16 08:53:10 CEST 2012

Devin Jeanpierre wrote:

> Although, it's worth mentioning that doctest is an interesting
> exception to all this: it uses regexps to parse out comments, which
> are used as directives for the test runner. However, doctest only
> touches code that is explicitly meant to be touched by doctest, 

The normal way of running doctest is to use implicit test discovery: you point 
doctest at a module, and it will discover your doctests without you needing to 
explicitly list them.

That's why there is a doctest directive to *disable* tests, but no directive 
to enable them: you only need to explicitly turn tests off, not turn them on.

> and that code generally doesn't need comments at all.

I write many functions or classes that include both documentation in the 
docstring, including doctests, and implementation comments in the body of the 
function. Docstrings and comments in the body of a function have very 
different purposes, just because a function has one doesn't mean that it won't 
have the other.


More information about the Python-ideas mailing list