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?
3 comments:
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.
+1
I'm doing most of my python development on a 13" laptop, so I also think no extra spaces are needed
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
Post a Comment