WHY does it look so puuurrrtyy?

[rating: beginner]

PEP-8 is Pythons code style guide. It tells you how to format class, function & variables names, use whitespace for improved (or simply consistent) readability, and many other things.

What’s the point?

Having uniform code style helps everyone become familiar with what reading the code should look like. There is a flow state where the code can be skimmed to quickly acquire a sense of what the code is doing, & where to find relevant information. Maintaining code is typically a combination of this flow state - quickly acquiring information & then slowing down to think carefully about specific sections. Code that is inconsistent in style breaks that flow & forces the reader to think consciously & slowly about all of it, instead of just some of it.

Code that is non-conformant can even be a hint that something needs to be investigated. For example, to a team that consistently uses style formatting, it suggests that the contributor may have been rushing and therefore more care should be taken in review to check for errors.

Generally speaking there’s too many things involved in maintaining consistent code style for a person to remember and apply correctly all the time. By using an “off the shelf” formatting tool, nobody has to think about style any more - just use the tool(s) and it’s the same everywhere.

Using PEP-8

PEP-8 compliant formatting tools like isort, black & flake8 are useful & important.

A famous quote from PEP-8 you might have seen around is:

Unfortunately this is often used to justify ignoring code style guidelines and doing your own thing. In my experience this is a poor choice.

Any project starting from scratch should make sure to be PEP-8 compliant, especially if it is going to be open source. It just means that more people are going to find the code easy to read & understand because more people are familiar with PEP-8 style, whether they realize it or not.

The more important statement from PEP-8 is this one:

An important thing to keep in mind is that most PEP-8 formatting tools will only adjust formatting, they won’t rename variable, function or class names because of the potential side-effects for someone using the code.

I have reformatted many projects into PEP-8 style in the past. If you’re just using isort, black & flake8, they will not change names in the code so there’s typically a big improvement in readability while maintaining the legacy naming conventions for compatibility.

If you really want to update variable, function & class name formatting there are separate tools that will do so, with varying degrees of success - good judgement required.

So here’s my summary:

1. Always use formatting tools before committing code to source control. Use tools like pre-commit & invoke to facilitate that.

2. Make it part of your CI pipeline to check that committed code is style compliant & fail the pipeline if not.

3. Use formatters on legacy projects provided they don’t adjust variable, function or class names. Be aware that when formatting is first applied to a legacy project there will be lots of changes to the code that don’t impact its function.

4. Variable function & lambda names should be snake_case

5. “Constants” (a convention, not language syntax) should be SHOUTING_CASE . The exception is inside functions where flake8 insists that variables & constants always be snake case.

6. Class names should be CamelCase

References

https://pep8.org/

https://pre-commit.com/

https://www.pyinvoke.org/

https://flake8.pycqa.org/en/latest/

https://github.com/psf/black

https://pycqa.github.io/isort/

I'm Russell 🐿️. A long time engineer discovering new life as a first-time solopreneur.

I build software delivery systems using Docker & Python automation that increase speed & reduce errors - saving money & improving profitability.