[PATCH] Re: more consistent style

[Nicolas Sebrecht]

On Mon, Jan 12, 2015 at 03:21:48AM +0300, Eygene Ryabinkin wrote:

> Should probably be
> {{{
>         """config.get with defaults.
> 
>         Same as config.get, but returns the value of `default`
>         if there is no such option specified.
>         """
> }}}
> since PEP8 says that it's the way to go,
>   https://www.python.org/dev/peps/pep-0008/#documentation-strings
> 
> 
> My personal preference is
> {{{
>         """
>         config.get with defaults.
> 
>         Same as config.get, but returns the value of `default`
>         if there is no such option specified.
> 
>         """
> }}}

Yes, I that's what I've seen from the code. :-)

> since it is more readable to my eyes, but I can live with PEP8's way
> of doing that.
> 
> Any views on this?

I think you are right about PEP8. Honestly, I don't know and I didn't
check because I don't care much about following all the PEPs outside.

I left almost all style issues to the contributors for years. Today,
while I'm working on a lot of files and I'm doing a lot of reviews I
realized that style could be too much inconsistent. That's why these
patches.

I decided to go with the more compact style

def function(<args>):
    """Little description
<blank line>
    More detailed description
    taking multilples lines."""
<blank line>
    First statement


with the exception of params/returns descriptions not taking the closing
triple quotation marks at the same line to avoid offending characters to
the correct understanding of the params description.

def function(<args>):
    """Little description
<blank line>
    :param: foo
    :param: bar
    """
<blank line>
    First statement


When it comes to style we certainly go to personal preferences and I
applied mines up to a certain level. I certainly hate the closing
quotation marks sticked to the first code statement like that

def function(<args>):
    """Little description
<blank line>
    More detailed description
    taking multilples lines.
<blank line>
    """
    First statement

...because it hurts me to have the function description more attached
to the block than the function name holding all the required blocks to
make the description valid.

In the case of no one-line description, I came to the compact style

def function(<args>):
    """Long description
    on multiples lines."""
<blank line>
    First statement


Now that I've detailed the general approach I've taken, I find you are
right about the specific case you raise in the sense that adding a short
description makes it better.

-- 
Nicolas Sebrecht