On 23 June 2014 07:04, Jay Pipes <jaypi...@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 <rbtcoll...@hp.com> Distinguished Technologist HP Converged Cloud _______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev