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.