On 06/24/2014 10:34 AM, Robert Collins wrote:
On 23 June 2014 07:04, Jay Pipes <[email protected]> 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.
"""
This is a summary.
And this is a description
"""
will result in a failure of H404, due to the "This is a summary." not
being on the first line, like this:
"""This is a summary.
And this is a description
"""
It is that silliness that I deplore, not the summary line followed by a
newline issue.
-jay
_______________________________________________
OpenStack-dev mailing list
[email protected]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
