[Python-Dev] PEP 8 updates/clarifications

[Ian Bicking]

Barry Warsaw wrote:
> It does seem like the more popular convention is to use "cls" than
> "class_".  I'll admit the latter does look kind of ugly.  Maybe the
> suggestion should be to use either a trailing single underscore or an
> abbreviation instead of a spelling corruption.  We could then list some
> common attribute names for common keywords, e.g. cls for class (what
> else?).

I personally feel "cls" should be used for classmethods, and not 
elsewhere.  Just like I wouldn't like someone using "self" outside of 
the first argument of instance methods.  So class_ still would be a good 
spelling elsewhere.

Most other keywords don't come up in my experience.  Suggestions for 
some non-keyword abbreviations might be useful, particularly for list, 
dict, and type, which come up a lot.  I often use lst, d, and t, but I 
don't actually like any of them.  I personally am comfortable reusing 
the variables dir, input, and vars, as I never use them in code.  id, 
type, and file are somewhere in-between.  I'll use the name of builtin 
as function arguments if it is meant to be used as a keyword argument, 
and the name is appropriate.

I'm not really sure there's a useful conclusion we can come to on these.

> Also, I have some additional guidelines adapted from the Mailman coding
> standards: http://barry.warsaw.us/software/STYLEGUIDE.txt

I looked at that too, but most of these didn't jump out at me.  I'll 
copy in the parts that aren't already in PEP 8 that seem possible:

   From-imports should follow non-from imports.  Dotted imports should 
follow
   non-dotted imports.  Non-dotted imports should be grouped by increasing
   length, while dotted imports should be grouped roughly alphabetically.

This seems too complex to me for PEP 8.

   In general, there should be at most one class per module, if the module
   contains class definitions.  If it's a module of functions, that's fine,
   group them as common sense dictates.  A class-containing module can also
   contain some helper functions, but it's best to keep these non-public
   (i.e. use a single leading underscore).

This doesn't effect me that much as a library user, and I'd defer to 
whatever the package maintainer preferred in terms of file layout.

- Right hanging comments are discouraged, in favor of preceding comments.
   E.g.

     foo = blarzigop(bar)  # if you don't blarzigop it, it'll shlorp

   should be written as

     # if you don't blarzigop it, it'll shlorp
     foo = blarzigop(bar)

I agree with this, but only as a loose suggestion.

There's some sections on vertical whitespace and ^L.  In these cases I'd 
defer to the package maintainer, like with file layout.  The PEP has 
some suggestions, which I think are sufficient.

- Unless internal quote characters would mess things up, the general rule is
   that single quotes should be used for short strings, double quotes for
   triple-quoted multi-line strings and docstrings.  E.g.

     foo = 'a foo thing'
     warn = "Don't mess things up"
     notice = """Our three chief weapons are:
              - surprise
              - deception
              - an almost fanatical devotion to the pope
              """

This is more prescriptive than would be appropriate for PEP 8.  It might 
be lightly suggested that double quotes signify "data", while single 
quotes signify "symbols".  But I think that might be too subtle a 
distinction for the PEP.  I personally don't care about this, and quotes 
for docstrings are already covered.

   Do not indent subsequent lines in a triple-quoted string; you should
   consider the opening quote to be the left margin.

I don't understand exactly what you are saying here.

   Always use True and False instead of 1 and 0 for boolean
   values.

I would agree.

-- 
Ian Bicking  /  ianb at colorstudy.com  /  http://blog.ianbicking.org