PyWart: PEP8: A cauldron of inconsistencies.

[rantingrick]

I believe the current Python style guide is inconsistent. The author
again allowed hie emotion to get in the way of logic. I will be
posting blocks of text from the PEP8 and commenting below them.

> ----------------------------------------------------------
> One of Guido's key insights is that code is read much more
> often than it is written.  The guidelines provided here
> are intended to improve the readability of code and make
> it consistent across the wide spectrum of Python code.  As
> PEP 20 [6] says, "Readability counts".
> ----------------------------------------------------------

Yes but this guide itself is contradictory Mr Van Rossum.

> ----------------------------------------------------------
> A style guide is about consistency.  Consistency with this
> style guide is important.  Consistency within a project is
> more important. Consistency within one module or function
> is most important.
> ----------------------------------------------------------

Hmm, Yes. And CONSISTENCY within a style guide that promotes
CONSISTENCY should trump them all! However as we'll see shortly
"CONSISTENCY" has been sacrificed at the alter of fluffy feelings and
multi-style-ism.

> ----------------------------------------------------------
> But most importantly: know when to be inconsistent --
> sometimes the style guide just doesn't apply.  When in
> doubt, use your best judgment.
> ----------------------------------------------------------

WRONG! When in doubt be consistent! There should be one AND ONLY ONE
obvious way to do it! When we have multiple ways of doing the same
thing we induce an overhead into our work flows. Instead we need to
follow the zen; in other words, BE CONSISTENT!

> ----------------------------------------------------------
> Look at other examples and
> decide what looks best.  And don't hesitate to ask!
> ----------------------------------------------------------

NO, NO! Follow the community standards. NEVER make up your own. We
cannot keep propagating multiplicity or else we will drown in it! We
cannot have people making up syntax for iterations can we? Likewise we
cannot allow people to make up styles.

> ----------------------------------------------------------
> Two good reasons to break a particular rule:
>
> (1) When applying the rule would make the code less
> readable, even for someone who is used to reading code
> that follows the rules.
>
> (2) To be consistent with surrounding code that also
> breaks it (maybe for historic reasons) -- although this is
> also an opportunity to clean up someone else's mess (in
> true XP style).
> ----------------------------------------------------------

Number two is the ONLY reason why ANYONE should not follow the style
guide to a "T"! However, code of this style should be shamed by the
community.

> ----------------------------------------------------------
> Use 4 spaces per indentation level.
> ----------------------------------------------------------

This should be the only acceptable indention level allowed by the
interpreter. All other indention should cast plagues of syntax errors
on the unrighteous.

> ----------------------------------------------------------
> For really old code that you don't want to mess up, you
> can continue to use 8-space tabs.
> ----------------------------------------------------------

NO! You should convert the code to 4 space tabs and move into the 21st
century. Stop living in the past. We must move forward... kicking and
screaming if necessary.

> ----------------------------------------------------------
> Tabs or Spaces?
>
> Never mix tabs and spaces.
>
> The most popular way of indenting Python is with spaces
> only.  The second-most popular way is with tabs only.
> Code indented with a mixture of tabs and spaces should be
> converted to using spaces exclusively.  When invoking the
> Python command line interpreter with the -t option, it
> issues warnings about code that illegally mixes tabs and
> spaces.  When using -tt these warnings become errors.
> These options are highly recommended!
> ----------------------------------------------------------

Here is another missed opportunity to force compliance of a style
convention. Mixing tabs and spaces should throw syntax errors! Is it
too much to ask that people at least choose one over the other? Sheez,
are we that afraid of offending them? Are these people emotional
basket cases riving with suicidal tendencies? *rolls-eyes* If they are
then the Python style guide is the LEAST of their problems.

> ----------------------------------------------------------
> Blank Lines
>
> Separate top-level function and class definitions with two
> blank lines.
>
> Method definitions inside a class are separated by a
> single blank line.
> ----------------------------------------------------------

This should be the law. Unfortunately many stdlib modules do not
follow this suggestion. In Python4000 i'm making it a syntax error to
include ANY blank lines in a func/meth body.

> ----------------------------------------------------------
> Extra blank lines may be used (sparingly) to separate
> groups of related functions.  Blank lines may be omitted
> between a bunch of related one-liners (e.g. a set of dummy
> implementations).
> ----------------------------------------------------------

NO! If you think that you need spaces in a function/method body then
that should be a giant clue that you need to either (A) move some
parts of the body out to other functions or (B) insert a comment.

Python4000 will not allow spaces in bodies of functions. If you want a
space you must use at minimum a single "#" char on that line or suffer
the syntax error.

> ----------------------------------------------------------
> Encodings (PEP 263)
>
> Code in the core Python distribution should always use the
> ASCII or Latin-1 encoding (a.k.a. ISO-8859-1).  For Python
> 3.0 and beyond, UTF-8 is preferred over Latin-1, see PEP
> 3120.
> ----------------------------------------------------------

no, NO, NO!. We should never be writing source in ANYTHING besides
ASCII. Can you offer any "good reason" why we should? No, because
there are no good reasons. This is just more fluffy feel good crap and
it makes me sick! Are we trying to keep xah happy? I know he likes
Unicode.

> ----------------------------------------------------------
> - Imports should usually be on separate lines, e.g.:
>
> Yes: import os import sys
>
>  No:  import sys, os
>
> it's okay to say this though:
>
> from subprocess import Popen, PIPE
> ----------------------------------------------------------

I disagree with this. I have no problem with logical grouping of
imports.

import os, sys,
import zipfile, tarfile, shutil
import itertools, functools, operator
import math, cmath, decimal, fractions, random

This is an example of allowing some freedoms of expression.

> ----------------------------------------------------------
> Imports are always put at the top of the file, just after
> any module comments and docstrings, and before module
> globals and constants.
> ----------------------------------------------------------

Not always GvR! For unit test i will allow "unit-test-specific-
imports".

if __name__ == '__main__':
    import "something only for unit testing"

However in all other cases imports MUST be at the top of file. NO
EXCEPTIONS!

> ----------------------------------------------------------
> Documentation Strings Conventions for writing good
> documentation strings (a.k.a. "docstrings") are
> immortalized in PEP 257 [3].
> ----------------------------------------------------------

Yes but they need some updating also. Search the archives for my
thread titled:

  "Proposal to extend PEP 257 (New Documentation String Spec)"


[WARNING: Inconsistencies ahead!]
> ----------------------------------------------------------
> Naming Conventions The naming conventions of Python's
> library are a bit of a mess, so we'll never get this
> completely consistent
> ----------------------------------------------------------

Yes we know all too well

> ----------------------------------------------------------
>  -- nevertheless, here are the
> currently recommended naming standards.  New modules and
> packages (including third party frameworks) should be
> written to these standards, but where an existing library
> has a different style, internal consistency is preferred.
> ----------------------------------------------------------

However we "can" fix this mess. Python4000 is the cure! But we need to
start now. This will be the greatest challenge this community has ever
faced. With the attitudes around here i'd our chances of overcoming
this multiplicity and inconsistency is very slim. However, we shall
face our enemies in battle nonetheless.

> ----------------------------------------------------------
>  Descriptive: Naming Styles
>
> There are a lot of different naming styles.  It helps to
> be able to recognize what naming style is being used,
> independently from what they are used for.
> ----------------------------------------------------------

Sorry but we don't need a Sunday school class discussion about every
style available. We just need to discuss what is expected of the folks
who write Python code.

> ----------------------------------------------------------
> Package and Module Names
>
> Modules should have short, all-lowercase names.
> Underscores can be used in the module name if it improves
> readability.
> ----------------------------------------------------------

No, underscores should ONLY be used in packages for "sub package"
modules!

> ----------------------------------------------------------
> Since module names are mapped to file names, and some file
> systems are case insensitive and truncate long names, it
> is important that module names be chosen to be fairly
> short -- this won't be a problem on Unix, but it may be a
> problem when the code is transported to older Mac or
> Windows versions, or DOS.
> ----------------------------------------------------------

Who cares about legacy OS's? DOS has gone the way of the do-do and
anyone who refuses to upgrade from windows 95 deserves what they get!
There is NO excuse to be running windows 95 in the year 2011! NO
REASON!

> ----------------------------------------------------------
> When an extension module written in C or C++ has an
> accompanying Python module that provides a higher level
> (e.g. more object oriented) interface, the C/C++ module
> has a leading underscore (e.g. _socket).
> ----------------------------------------------------------

BIG mistake here! All "C" extension modules should be prefixed with a
(guess what?) a "C_"!

 C_pickle.py
 C_module.py
 C_blah.py

Why? because pakages are going to want to use single and double
leading underscores for modules within the package. Be smart when you
create a naming convention. This single undersore was one of your
greatest follies and will come back to haunt you very soon! Python4000
won't have this problem though.

> ----------------------------------------------------------
> Class Names
>
> Almost without exception, class names use the CapWords
> convention. Classes for internal use have a leading
> underscore in addition.
> ----------------------------------------------------------

NO, NO, and F-NO! WITHOUT EXCEPTION all class identifier must use the
cap words convention. If the compiler sees the word {class} followed
by {SPACE} followed by a {lowercase letter} then a syntax error should
be raised. We cannot ask "nicely" about these things. We must enforce
them! People are lazy. If you give them choices they will propagate
multiplicity. Give them prophylactics in the form of forced syntax and
this plague of crack baby styles will be behind us.

> ----------------------------------------------------------
> Function Names
>
> Function names should be lowercase, with words separated
> by underscores as necessary to improve readability.
> ----------------------------------------------------------

Yes.

> ----------------------------------------------------------
> mixedCase is allowed only in contexts where that's already
> the prevailing style (e.g. threading.py), to retain
> backwards compatibility.
> ----------------------------------------------------------

And that's ONLY people! ONLY. What part of ONLY don't you seem to
understand?

> ----------------------------------------------------------
> Method Names and Instance Variables
>
> Use the function naming rules: lowercase with words
> separated by underscores as necessary to improve
> readability.
> ----------------------------------------------------------

NO! never name a variable using the "lowercase_with_underscores"
convention because it looks like a function! Instead use camelCase.

> ----------------------------------------------------------
> Use one leading underscore only for non-public methods and
> instance variables.
>
> To avoid name clashes with subclasses, use two leading
> underscores to invoke Python's name mangling rules.
>
> [...]
>
> Constants
>
> Constants are usually defined on a module level and
> written in all capital letters with underscores separating
> words.  Examples include MAX_OVERFLOW and TOTAL.
> ----------------------------------------------------------

Python needs REAL constants; you know, the ones that cannot be
changed? And to declare a constant it must be in all caps, or guess
what, it's not a constant, it's a variable you rebellious little
propagator!

> ----------------------------------------------------------
> - For sequences, (strings, lists, tuples), use the fact
> that empty sequences are false.
>
> Yes: if not seq: if seq:
>
> No: if len(seq) if not len(seq)
> ----------------------------------------------------------

This is a flaw in the language that i intend to fix. "if not seq" is
too ambiguous. The reader MUST know that seq is a seq and NOT a
Boolean. And when i say Boolean i am referring to True|False only! Not
zero or one, or empty string or non-empty string, etc, etc!

> ----------------------------------------------------------
> Copyright This document has been placed in the public
> domain.
> ----------------------------------------------------------