Open Stack

On 23 June 2014 07:04, Jay Pipes <jaypipes at gmail.com> wrote:

> I would also love to get rid of H404, otherwise known as the dumb rule that
> says if you have a multiline docstring, that there must be a summary line,
> then a blank line, then a detailed description. It makes things like this
> illegal, which, IMHO, is stupid:
>
> def do_something(self, thing):
>     """We do something with the supplied thing, so that something else
>     is also done with this other thing. Make sure the other thing is
>     of type something.
>     """
>     pass
>
> Likewise, I'd love to be able to have a newline start the docstring, like
> so:
>
> def do_something(self, thing):
>     """
>     We do something with the supplied thing, so that something else
>     is also done with this other thing. Make sure the other thing is
>     of type something.
>     """
>     pass
>
> But there's a rule that prevents that as well...
>
> To be clear, I don't think all hacking rules are silly. To the contrary,
> there are many that are reasonable and useful. However, I'd prefer to focus
> on things that make the code more readable, not less readable, and rules
> that enforce Pythonic idioms, not some random hacker's idea of good style.

So
"""
Lorem ipsum

Foo bar baz
"""

is a valid PEP-257 docstring, though a bit suspect on context. In fact
*all* leading whitespace is stripped -

"""foo"""

and

"""
foo
"""

are equivalent for docstrings - even though they aren't equivalent for
the mk1 human eyeball reading them.

So in both cases I would have expected to you be bitten by the
first-line rule, which exists for API extractors (such as
help(module)) so that they have a useful, meaningful summary they can
pull out. I think it aids immensely in docstring readability - and its
certainly convention throughout the rest of the Python universe, so
IMO it comes part of the parcel when you ask for Python.

-Rob


-- 
Robert Collins <rbtcollins at hp.com>
Distinguished Technologist
HP Converged Cloud