Nitpicking about coding standards (was Re: [Zope-dev] zope.sendmail grantma-retryfixes branch review)

[Marius Gedminas]

On Thu, Mar 20, 2008 at 10:33:10PM +0000, Chris Withers wrote:
> Marius Gedminas wrote:
>>> +        """Process results of an SMTP error
>>> +           returns True to indicate break needed"""
>> The standard docstring convention is to do this:
>>            """Process results of an SMTP error.

There was a blank line here that you omitted.

>>            Returns True to indicate break needed.
>>            """
>
> This standard sucks.
>
>             """
>             Process results of an SMTP error.
>
>             Returns True to indicate break needed.
>             """
>
> ...is much more readable. If there's a tool that does something silly with 
> this, fix the tool.

It's a matter of taste, perhaps, because I do find

    """Short sentence.

    Longer description.
    """

nicer than your example.  Luckily, PEP-8 agrees with my taste. :-)

Okay, I lied.  PEP-8 says to add an extra blank line before the closing
""" (because Emacs' paragraph wrapping command sucks), and thus you get
this:

    """Short sentence.

    Longer description.

    """

but I don't recall ever seeing this variant in the Zope 3 tree.  I
completely agree with your sentiment (fix the damn tool!) here.  My
beloved vim can format the longer description without touching the
trailing """.

>> Also, it's conventional to leave two blank lines between class and
>> interface declarations.  (PEP-8 says this.)
>
> What does this actually mean? I couldn't follow from your example.

I'll try to give a better example.  Count the blank lines in it:

------------------------
class OneClass(object):
    """Docstring."""

    def a_method(self):
        """Docstring."""
        code
        code
        code

    def b_method(self):
        """Docstring."""
        code
        code


class AnotherClass(object):
    """Docstring."""

    def a_method(self):
        """Docstring."""
        code
        code


class ThirdClass(object):
    """Docstring."""
-------------------------

Class definitions are separated by two blank lines.  Method definitions
are separated by a single blank line.  That's what PEP-8 says.

> Other than that, completely agree with everything you said :-)

It's always the little and unimportant things that get the most
attention and discussion.

On the other hand, at least we have a consensus (PEP-8) in the Python
community, unlike those poor C++ brace style flame war veterans.  I
suppose having no braces helps ;-)

Cheers!
Marius Gedminas
-- 
The day after tomorrow is the third day of the rest of your life.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://mail.zope.org/pipermail/zope-dev/attachments/20080321/bfc790cf/attachment.bin