Open Stack

On 06/24/2014 10:34 AM, Robert Collins wrote:
> 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.

"""
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