The quest for the "definitive Python style guide"

Hey there,

Code style guidelines are an endless source of discussions and arguments among developers.

A while ago, newsletter member Andrew reached out to me with this question:

~~~

Hi Dan,

I've been enjoying your email updates and python tips! Thank you for doing this! I have a quick question. For someone new to Python, I'm trying to find the definitive style guide. A quick Google search turns up things like this:

https://www.python.org/dev/peps/pep-0008/
https://www.python.org/dev/peps/pep-0257/
https://google.github.io/styleguide/pyguide.html

Although it appears the first link has been updated, the first two seem rather old (2001)? Are these still the main go-to style guides? The next one looks to have been created by Google...but why would they do this if a definitive guide already exists?

As a contrast, the PHP-FIG page provides an excellent, and well laid-out recommended style guide: http://www.php-fig.org/psr/psr-1/

I guess I'm looking for the equivalent to that. I much appreciate any help you can offer. And again thank you for your emails and video tutorials!

~~~

One of the things I like the most about Python is it's high readability.

I strongly believe that "code is communication"—

And just like there are generally accepted stylistic rules & guidelines for written communication in English, there are code style guides for writing Python.

Sticking to these guidelines is one honking great idea.

They make it easier for development teams to work together. And even if you're working on a project by yourself, they'll help you make changes in the future.

My thinking there is this:

When you're reading code, your brain works like a Python compiler.

It first needs to parse the program text and then turn it into some internal representation before you can understand and modify the code.

If your code uses inconsistent styling and formatting rules, it trips up your brain's pattern recognizer and slows it down.

Therefore it takes longer to read and modify "sloppy" code.

And these "micro delays" add up and cost you productivity. They also make you feel exhausted quicker.

(I can't cite scientific proof for this theory, but from experience it's what I think happens. I talk about this a lot in my code review videos on YouTube.)

Alright, back to the original question, which sort of went like this:

"Okay great, but WHICH style guide should I use?"

Actually, the style guides Andrew mentioned are the most commonly used ones in Python.

Some people don't like Google's Python style guide because it has some "Google-isms" in it (how import statements are laid out etc.)

I'd say Google's guide is worth a read for a second opinion, but:

Generally the PEP 8 style guide is the preferred choice in the community and I also recommend and use it personally.

It's a great idea to mix PEP 8 with PEP 257 for docstring conventions. Those two make a great combo.

And yes, PEP 8 and PEP 257 are rather "well-seasoned"—which is NOT a bad thing.

These style guides have been maintained and fine-tuned for over a decade. Both are valuable resources that any Python developer worth their salt should know.

If you're ready to jump in but you're looking for an easier to read web-version of PEP 8 with improved formatting, check out pep8.org.

Happy Pythoning!

— Dan Bader