Python Violates PEP 8

Sweigart's Law of PEP 8 Complaints is: "Any time someone complains about source code violating PEP 8, they are always complaining that the source code uses camelCase instead of snake_case. The complaint is never about any other part of PEP 8." What is the point of Python Enhancement Proposal document number 8, and how does it get used and misused? Why do we write code the way we do, and how meaningful are conversations about code style and readability?

The What and Why of PEP 8

PEP 8 details the coding conventions for writing Python code. Coming from Python's creator and core devs with decades of history in the Python community, PEP 8 carries a heavy weight of authority. A consistent code style is key to code readability. Code readability is at once an objective measure and subjective opinion, a sign of mature engineering practice and an utterly irrelevant triviality. So of course it's something nerds argue about on the internet.

"Code is more often read than written," is a common phrase in software engineering. It correctly points out that you and other developers will need to read code to understand it whenever they make changes for bug fixes or new features. One early source for this quote is from the Ada 83 Language Reference manual:

The need for languages that promote reliability and simplify maintenance is well established. Hence emphasis was placed on program readability over ease of writing.

But code readability isn't necessary to have a correctly working program. The computer doesn't care about your choices of spacing and variable names. And developers under deadlines have the pressure to simply write code first and make it readable later. Chapter 3 of my book, Making Games with Python & Pygame even has a version of the Memory Puzzle game with all variable and function names rewritten as random letters. The program works just fine. (And LLMs like ChatGPT have no problem understanding it.) But show code like this to a human programmer, and they're perplexed:

def f(bbb, pp):
    for bb in range(10):
        for ee in range(7):
            oo, ddd = aa(bb, ee)
            if not pp[bb][ee]:
                pygame.draw.rect(b, (255, 255, 255), (oo, ddd, 40, 40))
            else:
                ss, tt = s(bbb, bb, ee)
                w(ss, tt, bb, ee)

You don't need a dramatic example like this to make the case. Even small readability flaws can cause speed bumps to understanding. This is why PEP 20, "The Zen of Python", has the line, "Readability counts." (And the Zen also has the line "There should be one-- and preferably only one --obvious way to do it.", an indirect blow to Perl's brag of "There's more than one way to do it!" It turns out that when Perl gives you several ways to do the same thing, Perl programmers need to learn all five ways to understand Perl programs.)

PEP 8 gives several directives for writing (in its opinion) readable code. However, I think the most important part is the first section right after the introduction, "A Foolish Consistency is the Hobgoblin of Little Minds":

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 says, “Readability counts”.

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 the most important.

However, know when to be inconsistent – sometimes style guide recommendations just aren’t applicable. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don’t hesitate to ask!

In particular: do not break backwards compatibility just to comply with this PEP!

PEP 8 itself is pragmatic about when to apply PEP 8. PEP 8 was written to give guidance on consistency, including when a project's code style is different from PEP 8's guidelines. This section, which comes before all the other sections about code style, is a big "within reason" caveat for the document. But never underestimate the ability of software nerds to start arguments.

Bike Shedding

"Bike shedding" or Parkinson's Law of Triviality points out a disproportionate amount of focus is given to trivial (but easy to understand) issues. Discussing a document on the design of a nuclear power plant will tend to have an outsized amount of discussion on what color to paint the facility's bicycle shed.

Within open source projects, there's an urge to get submission accepted (no matter how small) so that one can claim the title of "contributor." However, software projects are complex and often require a large initial investment of effort before one can make any contribution at all. The temptation, then, is to submit pull requests for trivial details.

On the other end, experienced (but not necessarily mature) software developers can believe that the way they style their code is the one true way to style code, and insist that a project adopt their own style.

All code changes involve some level of risk that they will unintentionally introduce bugs. While "if it ain't broke, don't fix it" can sometimes cause projects to put up hurdles in front of improvement, it's important prevention against "change for the sake of change."

In both cases, "because PEP 8 says so" is an easy reason to cite for the style changes.

Sweigart's Law of PEP 8 Complaints

PEP 8 includes lots of provisions for styling code: limiting comments to a line length of 72 characters, placing operators at the front of the line in multiline expressions rather than the end, and using trailing commas at the end of a list's items (but only if the list spans across multiple lines; single line lists should not have a trailing commas.)

But these guidelines are of no matter, since no one complains if your code base violates them. There is, however, one part of PEP 8 that is universally cited, so I've declared it Sweigart's Law of PEP 8 Complaints:

"Any time someone complains about source code violating PEP 8, they are always complaining that the source code uses camelCase instead of snake_case. The complaint is never about any other part of PEP 8."

When a variable name includes multiple words, there are two common ways to separate them: snake_case which separates words with an underscore, and camelCase which separates words by capitalizing the first letter of subsequent words makingThemGoUpAndDownLikeTheHumpsOfACamel.

I prefer camelCase. I find it easier to type because I don't have to type an extra underscore and camelCase appears (to me) just as readable. PEP 8 advises snake_case. I would say this means I violate PEP 8, except that PEP 8's "A Foolish Consistency is the Hobgoblin of Small Minds" explicitly states that it's okay to violate PEP 8 and that consistency within a project is what's important.

The first and second editions of my book, Automate the Boring Stuff with Python, use code examples with camelCase. Guess what the most common complaint of that book was?

It wasn't the comments that are longer than 72 characters.

It's certainly possible that theoretically someone might cite some other part of PEP 8, but I've never seen it myself. There are and quite possibly still are flaws with my book. But those are looked past when "his book doesn't follow PEP 8" is within such easy reach.

In the third edition, I made the laborious choice to convert all of the code examples in this 600-page book to snake_case. The code worked the exact same as before (the Python interpreter doesn't care which style you use) and whether the code was "more readable" is debatable and I don't want to debate it.

Oddly enough, my book still violates PEP 8 in all the other ways it always had. But I haven't seen a single complaint of "doesn't follow PEP 8" for the third edition.

The Point of Code Style Guidelines

The point of code style guidelines is to prevent arguments. Should curly braces open at the end of a line or at the start of the next line? The mature, well thought out answer to this is, "Whatever. Let's just pick one and move on." It doesn't matter if you drive a car on the right side or the left side, as long as you are driving on the same side as everyone else.

Code style guidelines are meant to stop these arguments by providing the consistent rules to abide by. These can be enforced by code formatters such as Black or Ruff. This is important: software developers' time is expensive and tedious arguments are a costly waste.

But to those determined to fight on their hill, this only moves the argument from "what does the style guideline say" to "what should the style guideline say". These arguments aren't winnable. If you give in to one loud voice, another loud voice will insist that it needs to be changed back. Appeals to the style guide are often just the selective enforcement of the complainer's personal preference. And if the style guide is out of line with their personal preference, they'll cite Google's style guide, or Django's style guide, or the assumed opinions of computer scientists.

My advice:

• Ignore them. Don't reply to their emails. Leave their pull requests to collect dust. Agree with them, but point out that there are other PEP 8 violations you'd like them to add to their PR before you'll accept it. Ask that they create unit tests to search for future PEP 8 violations. Say that you have a policy against AI-generated contributions. What they're looking for is an easy effort way to put their mark on a project, but having to take ownership of their contribution to make it high quality usually ends with them giving up and going away.

• Ask them for the configuration set up for a code formatting tool such as Black or Ruff. They'll likely copy/paste something from the internet. Point out that it doesn't work on your machine. (It likely won't; they'll forget to update the pyproject.toml file or some other detail.) Don't fix it for them; make them put forward the effort that they are allergic to.

• Admit that they are right, but that unfortunately the project has already matured to the point that changes would break backwards compatibility. This has the twin benefits of telling them what they really want to hear while also being true. (See the next section.)

• Make the change, but in the smallest way possible. Sometimes it's easiest to give the baby its bottle. I did not change the third edition to follow PEP 8; I changed to use snake_case. This got rid of all of the "violating PEP 8" complaints, except from people still reading the older editions. When I say that style issues don't matter, I truly mean it: I'll go ahead and make the change if it shuts people up, because it doesn't matter either way.

This advice is part cynicism and part pragmatism. You can spend your time and effort in this short life trying to explain your trivial decisions to people who don't want to understand them. And there's always the chance that the complaints regarding software development have merit. (Here's the part where I begin a sentence with "but".)

However, code style is rarely one of them. Just set up your code formatting tool and leave it to handle style.

Python Violates PEP 8

But if you still aren't convinced and insist that dogmatically following PEP 8 is a worthwhile pursuit, my last argument is that Python itself doesn't follow PEP 8:

• Constants should be in ALL_CAPS, but the math module's constants don't: pi, e, tau, nan, and inf. Some constants are: os.SEEK_SET and os.O_RDONLY.

• Names should use snake_case, but the unittest module's setUp() and tearDown() use camelCase. The string methods isalpha() and startswith() and the datetime methods strftime() and strptime() don't use either approach!

• Capitalized names for constants should use an underscore to separate words, but the re module's IGNORECASE and DOTALL constants don't.

• Class names should begin with uppercase characters, but int, float, str, list, and dict don't.

• Names shouldn't include a prefix indicating a group, but st_mode, st_size, and st_mtime all have them.

There's countless other examples. Now, Python is an old language and many of these inconsistencies are due to historical reasons. But Python is so popular and well-established that "fixing" these would have an enormous cost for very little, if any, benefit. Even during the massive transition from Python 2 to 3, the issues I outlined above weren't considered worthy.

Software development is as much a social task as it is a technical one. Programs are in general too complicated to be maintained by one or two developers. Whenever you have three or more people in a group, politics occur. Add into this software engineers who confuse their opinions for universal mathematical truths, and there's always the chance for less than fruitful discussion.

I wish I had a more objective ruler to offer for identifying and dealing with needless productivity hurdles, but I feel like I've spent enough time on this blog post. I have to get back to work...