Tuesday, January 6, 2015

significant pep257 change

Python documentation standard

After getting used to putting a blank line before (for symmetry) and after (to separate the method) a class docstring, for what seems like an eternity (it's been in PEP257 for over 10 years I think), I was doing some code review today and was asked about why add a blank line between the class and docstring. So I quoted pep257:

Multi-line Docstrings
Insert a blank line before and after all docstrings (one-line or multi-line) that document a class -- generally speaking, the class's methods are separated from each other by a single blank line, and the docstring needs to be offset from the first method by a blank line; for symmetry, put a blank line between the class header and the docstring. Docstrings documenting functions or methods generally don't have this requirement, unless the function or method's body is written as a number of blank-line separated sections -- in this case, treat the docstring as another section, and precede it with a blank line.

I have a pep257 tool that highlights exactly that and the wording is still there on this site:

But, it appears that this disappeared from:

I also found this mercurial changeset:

Looks like Guido Van Rossum made the change. Any idea why, beside the fact that as BDFL he can?



Guido van Rossum said...

That section of the PEP didn't match common practice. E.g. check out what the stdlib uses; I believe you'll find nearly all classes don't have a blank line before the class docstring.

fruch said...


I'm doing most of my python development on a 13" laptop, so I also think no extra spaces are needed

Francois Dion said...

I get it, but it is surprising to change the yardstick... It's always possible to silence a specific warning, and the stdlib is not exactly conforming to pep257 and pep8 in general.

But, hey, what is done is done. I've submitted a PR:

In the meantime, it's possible to ignore D203 (the blank line before) by calling pep257 with --ignore=D203