This post is about something that everyone knows, except for the people who don’t: the 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:
- 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.
Good news: no, you don’t have to memorise all of it by heart. There are plenty 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, and if the naming is consistent, and many other important things. That’s why it makes sense to reread the PEP8 from time to time, to make sure that you don’t miss anything.
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.
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.
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.