PEP8 Style Guide, and why is it important?

This post is about something that everyone knows, except from the people who don’t: the PEP8 Style Guide.

What is PEP8 Style Guide?

The first comment I’ve got during my very first code review was, “You have 142 PEP8 errors.” And the first thing I thought was, ” … what’s PEP8?”

PEPs are Python Enhancement Proposals, and they describe and document the way python language evolves. They also provide a reference point (and a standard) for the pythonic way to write code. The PEP8 is the Style Guide for Python Code, and it covers:

  • formatting
  • comments
  • naming conventions

It also has a lot of programming recommendations and useful tips on various topics, which aim to improve readability (and reliability) of your code. If by any chance this is the first time you hear about PEP8, a question that may pop up in your head is, “Why should I care?”.
Here’s the short answer: all clever strategies for bypassing this topic lead to shooting yourself in the foot.

PEP8 plugins

Good news: no, you don’t have to memorize all of it by heart. There are plenty of plugins and command line tools that will check if your code is compliant with the PEP8 style guide, and even fix some for you – for example, trailing white spaces. But do not think that your code is PEP8 compliant if a plugin doesn’t give you any warnings. It can’t check if your variables have meaningful names or if the naming is consistent. That’s why it makes sense to reread the PEP8 Style Guide from time to time, to make sure that you don’t miss anything.

Consistent style in your code

Consistent style (formatting, naming… ) does to code what a consistent writing style does to a text: it makes it cleaner, crisper, easier to read and understand. Nobody likes to read text ThAt iS wRiTteN LiKe This, or that is written like dis (even though you can understand the meaning, right?). This is visual noise. Same as inconsistent indentation, too long lines, extra white space, and useless comments, and when you read code like that (even if it’s your own code), visual noise makes your mental resources deplete faster. Awkward grammar constructions, very long sentences make text incomprehensible. Just as well as in misleading or meaningless variable names and deep nests make you put extra effort into understanding what the code does.  And I’m sure that we all prefer to spend our energy in a more productive (and less frustrating) way.

Unified standards

Another reason to stick to PEP8 is to make collaboration on the project easier.  One obvious benefit is that it will enforce the same standards for all the developers. But there’s more: if some of the team members stick to pep8, they have their editors configured for an automatic compliance check. So every time they open your code, they’ll see warnings everywhere, which is really annoying. Then, their IDEs will remove trailing whitespace and extra white lines, which will lead to noise in commits, and even to conflicts for nothing. Don’t do that to your colleagues. Trust me, just don’t.

More on PEP8 Style Guide

There is plenty of literature written about clean code, and PEP8 is not a comprehensive style guide by any means. It is just a basic minimum requirement for python code. And if you think that you’ve got more important things to learn than code formatting guides, this may be the source of many of your code problems.



This site uses Akismet to reduce spam. Learn how your comment data is processed.