Open Stack

Our HACKING includes this requirement for multiline docstrings:

        [...] After you have finished your descriptions add an extra
        newline and close the quotations.

I propose that we remove this line and requirement from HACKING.  We
don't have to adjust all the docstrings to remove an extraneous space,
but we should not require that it be here.  Below is my defense:

This requirement has never made sense to me, and there does seem to be
some disagreement within nova about following this.  So, for more
insight, I went and read PEP 257, and discovered this rationale:

        The BDFL [3] recommends inserting a blank line between the last
        paragraph in a multi-line docstring and its closing quotes,
        placing the closing quotes on a line by themselves. This way,
        Emacs' fill-paragraph command can be used on it.

(The indicated footnote is just an explanation of the term "BDFL".)

So, the first point I want to make is that this was a recommendation of
PEP 257, rather than a requirement.  The second point is that it was due
to a limitation of the fill-paragraph command of a single editor.  And
the third point is that the editor in question, which happens to be my
editor of choice, no longer has this limitation, at least in recent
versions--fill-paragraph on docstrings terminated by triple-quotes
ignores the triple-quotes.  Therefore, I believe the recommendation no
longer has any substance behind it, and so it should no longer be
required of HACKING-conforming code for nova.
-- 
Kevin L. Mitchell <kevin.mitchell at rackspace.com>

This email may include confidential information. If you received it in error, please delete it.