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?

François
@f_dion

3 comments:

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...

+1

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:
https://github.com/GreenSteam/pep257/pull/91

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