7 tips to make an effective Python Style Guide

Style guide. Some teams refer to it as their coding manual, coding standards or coding conventions, they tend to refer to the same thing. A style guide is a set of standards, principles, and rules set by a team that each developer should follow.

Determining the most appropriate style guide for the team seems difficult. Usually, individual team members already have their own style of writing code (although this is more of sticking to certain principles, still) and usually do not want to change it. Software developers are conservatives and every change in the development process slows us down. Imagine that you have to change your handwriting every time you change a project. It's crazy, isn't it? But that doesn't mean there's no way to define and implement coding recommendations for your team. You just have to make the right argument on why a style guide is important.

Let's start from the beginning. Why are we even sitting in an office writing our applications? We are helping businesses make money or solve their problems. To make this happen, we develop solutions/products and put them into production where they can bring some value. We don't want our solutions to cause more problems and we want them to be useful for as long as possible. Of course, there are bugs. Sometimes it's just a broken code, and sometimes the price of an error is a blown-up spaceship. Of course, nobody makes errors intentionally, everybody tries to maintain code quality to the fullest possible extent. For this purpose, we build CI pipelines and development processes that will help us prevent failures and bugs in our product. As a result, the stages and distribution of the bugs turn out to be something like this:

These are the necessary steps to get the code into production. If you haven't passed one step, forgotten something or a reviewer said it won't work like that, you'll see the sign "failed" — bad code doesn't get into production. The code review is one of the top and most complicated steps of the pyramid: you cannot automate the code review, and when you do, it will lead to automating the whole programming. Then programmers will no longer be needed either. The style guide is just one of the tools to build such a process.

For some reason, python developers are sure that you need the style guide only to make your code consistent, but even PEP8 itself has devoted a whole paragraph to "readability counts" and mentions that the style guide should guide developers to avoid frequent project errors and code smells by introducing best practices to the development process(my representation). That's one of the main points why I don't recommend Black.

Other people see the style guide for the team as a method to make all developers be the same. Some people rebel when they are shown the style guide, believing that they can't do their job properly if someone tells them how to write code.

But the most important thing in any project is teamwork, in my opinion. It's unrealistic to do big projects alone and support them. And the most important part while working in a team is communication. Of course, developers are not very sociable people in most cases (that's why I don't speak at meetings and conferences) but we write and communicate a lot with each other with the help of code.

It is clear that the program doesn't care what your code looks like, but your teammates certainly care about it. How many times have you rewritten someone else's PR and, before doing anything else, indented it the way you like and split the logical parts? When everyone writes a code that looks different, everyone constantly tries to visually parse the code before they understand it. When everyone writes a code that looks familiar, understanding comes faster.

source

Keep in mind that your code must be supported and maintained by someone other than you. You do not just communicate with other members of your team in the present, you also communicate with your team members in the future.

The style guide, in my opinion, should correspond to the following points:

You need to make your stylus guide easy to use. No matter where no matter how it should be available to absolutely every team member at any time. So that any developer can reach it at any time — a page in the knowledge base, a piece of paper above the developer's workstation, phone app, screen saver, whatever.

It is very difficult to implement a style guide into an old development team with a large codebase. Usually, it leads to huge resistance and potential bugs (depending on how to implement it of course).

As your team grows and changes over time, your style guide will help you, onboard new team members faster.

Otherwise, every review in a large project will turn into a discussion of where to put the bracket and how to write the import.

The best way to make sure that nobody uses your style guide is to write it and then tell everyone else to obey it. The purpose of a style guide is to make sure that multiple authors write in a clear and unified way on how to write code. So it's best to bring other authors into the process of making decisions. It is desirable that the style guide is discussed by others. Plan on making revisions in light of feedback and the style guide will become something in which all interested parties can participate.

Remember that standards cannot be enforced unless everyone agrees on what that standard is.

Usually, style guides are made on the basis of existing guides with a focus on those points where there is no correct answer, but where one of the approaches is preferable for the project or team.

One good example would be more effective than a pile of text. Ideally, there should be a few examples — good examples and bad examples, and yes, they should be distinguishable.

To write an effective style guide, it is important to remember that most people in your company will hardly ever read it.

The style guide should be as automated and checked by the CI. This will greatly speed up code review by completely eliminating any bikeshedding on code style. It will make the team respect the style guide and at the same time developers will not have to read long texts, CI will tell what is wrong exactly.

In some cases, it's better to use autoformatters like yapf, autopep8, black, but don't rely too much on those tools.

No need to reinvent the wheel. Use existing guides or take them as a basis. Outside this starting point, your guide may change depending on your team, workflow, and technology. When your team makes new decisions about standards and practices, add them to your style guide.

There are many style guides in the wild. The standard PEP8. Google has style guides for everything. Gitlab has its style guide. The Django community has a good style guide.

Most of the new developers coming to the project are unlikely to immediately read the style guide. And as I told you automatization can make life easier and can force developers to use accepted code style. Nothing motivates the developer better than errors in the CI pipeline.

I have already told you about the good Python analysis tools. But there are other tools that make life easier.

Returning to the review code, the process usually looks like this: the code comes to the review, the reviewer finds errors, some of them he may have already seen in another PR and it is understandable that he does not want to see similar mistakes anymore. After 10 days, it's the same. A year passes — the same mistake. A new developer comes — the same mistake. Linter will help to automate it.

The most popular linter for Python is flake8. It doesn't contain many rules per se, but its main advantage is a large number of plugins, a list of which can be found here. There is also wemake-python-styleguide — a large list of rules for flake8. The authors have standardized everything that is possible, and it is unlikely that all rules will be followed.

Attach flake8 to your IDE, or at least run it before each commit. And try to fix every warning (until it hurts).

EditorConfig is another tool that is actually a configuration file and a set of extensions to a large number of code editors and IDE. Its task is to create a single settings file, and, once and for all solve issues such as "tabs or spaces" for all IDEs and all programming languages. Such a file can be stored in the project version control system, which will allow all its developers to use the same configuration.

Here is a sample .editorconfig file that defines indent rules for Python code:

root = true

# For all files we use unix-compatible line breaks
[*]
end_of_line = lf
insert_final_newline = true

# 4-space indents
[*.py]
indent_style = space
indent_size = 4

# For Makefile, release.Jenkinsfile and Dockerfile files only
[{Makefile, release.Jenkinsfile, Dockerfile}]
indent_style = tab
indent_size = 4

Create a .editorconfig and attach it to your IDE so that everyone's code is formatted the same way.

isort is a Python tool/library for sorting imports alphabetically, automatically divided into sections. It is very useful in projects where we deal with a lot of imports.

It's easy to organize the imports into sections, but it's very tedious to keep them in alphabetical order. I don't know about you, but sometimes I have to run all the letters in my head to be sure.

# sort the whole project
$ isort --recursive ./src/

# just check for errors
$ isort script.py --check-only

The last, final moment in code editing are strings. Someone likes to write them in single quotes, someone in double ones. To unify the whole project, there is a tool that allows you to automatically align with your style guide — unify

Usage:

$ unify --in-place -r ./src/

As everywhere else, the tool will perform its dirty work recursively for files in the folder.

So far we talk only about the code itself, but we have never talked about comments. The time has come — docformatter. This utility helps to bring your docstring under the PEP 257. The agreement specifies how documentation should be written. Using this tool is no more complicated than the previous ones:

$ docformatter --in-place example.py

There are also automatic code formatters now, here are the popular ones:

• yapf (here you can make a align with your own style guide)
• black(you don't need a style guide because you don't have a choice)
• autopep8 (makes your python script to conform PEP8 style guide)

I will tell you right away that I am against automatic code formatting in Python. Don't get me wrong, I would like to automate everything that is possible. But I think those tools are soulless, and code formatting should always be the developer's concern.

If we could automate the above processes and minimize the "human" interaction, we could focus more on the code logic and its implementation. Git-hook, namely pre-commit hooks is a piece of code that runs before each commit and determines whether or not to accept a commit. Think of it as the gatekeeper of your codebase. This script can be a checking tool or autoformatter, or both.

Do you want to make sure that you didn't accidentally leave PDB in your code? Hook for a pre-commit. Want to guarantee a clean, readable code that matches PEP8? Hook for a pre-commit. Want to run all unit tests in your codebase? You guessed right — git hook.

Using unified git hooks in the project is a kind of coercion for the developers, and if your team is more senior, you can try using Makefiles.

There is no ideal code formatting. There is no ideal development process. Everything consists of conditions and circumstances of specific companies' and projects' realities.

The general style guide for the language and the whole community is amazing and I like it. But don't be blind, if you really think they are universal, you can always do a bit better for yourself or your team, so you'd better take this step.

The theme of styles becomes really exciting when you have to dig around a lot in someone else's code.

Additional materials

• Python beyond PEP8
• Raymond Hettinger - Beyond PEP 8