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.
signature.asc
Description: Digital signature
_______________________________________________ Zope-Dev maillist - Zope-Dev@zope.org http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )