Richard Bucker

PEP-8 is an awful document

Posted at — Jul 10, 2011

Ordinarily I do not comment on RFC or PEPs and the like. They are written by people who are either experts in their fields (hopefully languages) or people who are clearly students of the art and craft of software development. That’s not to say this I follow these guidelines to the letter… for example “do not code defensively” from the erlang best practices document makes my skin crawl.So as I re-review PEP-8 I’m reminded of the first time it was introduced. It was not a pretty day or a fun time. It was everything that a good software development manager tells you can and will go wrong when the inmates run the asylum. So while I think it’s generally a good idea… I hate the PEP-8 partly because it’s poorly written and partly because the way the team deployed it. Maybe they are one in the same. (I don’t think anyone referred to Knuth’s work on documentation or documented code)So here is my summary of PEP-8 in order to cool things down and make it workable.NOTE 1: code is often read more than it’s written.NOTE 2: style guide is about consistency.NOTE 3: use your best judgement.Indentation: 4 spaces, no tabs. when wrapping lines use at least 8 spaces but keep the like items together.Line Length: limit all line lengths to 79 chars.Blank Lines: use sparingly. 2 between classes and 1 between methods.Encoding: ASCII or Latin-1, and with Python 3 use UTF-8imports: each import statement on it’s own line. group the imports by “standard python”, “3rd party :”, and “app specific”whitespace: good but do not go crazy. Add a single space in assignments but not in function declarations.single line: do not put multiple statements on a single line.NOTE 4: keep your comments up to dateblock comments: the same indent level as the codeinline comments: use sparingly.NOTE 5: see PEP-257 about docstringsversion: this only applies if you use CVS or subversion.  Since I use git and hg, they do not apply.naming conventions: whatever you use make it obvious and distinguishable. Avoid ambiguous lettering like ‘l’, ‘o’ .package or module:class:exception:global:function:function arguments:method names:instance variables:I’m into this for an hour already and I’m bored out of my mind. This just seems so obvious to me.design for inheritance:programming recommendations:So good luck with this. With any luck you’ll have a strong manager or boss. You’ll have a decent understanding and it’s won’t be confused with anything you used the other most recent language you’ve mastered. And that your intuition is something you can rely on. (remember reverse hungarian notation in OS/2 and Windows?)