Black Is the Way

Mando says “format your code”

Recently it dawned on my team that we were wasting too much time during code reviews because of formatting inconsistencies between new PRs and the rest of our codebase. Owning mostly JVM services and libraries, we decided to use IntelliJ IDEA’s Code Style editor to create code formats that the whole team could agree on — for Java, Groovy, and Kotlin. Of course, during the decision-making process, differing opinions came up around the most minute of details, such as line wrapping in various scenarios, indentation levels, etc — however, we persevered, applied the formatting to all our code, shared the format with our contributors, and called it a job well done.

However, while this exercise ended up with our team spending less time on syntax nitpicks going forward, we still spent a fair amount of time creating a code style guide and distributing it — but even with that, there were some issues.

The style choices were made by a team, and teams (and their opinions) change over time. We picked a specific vendor tool (IntelliJ IDEA), which, while a great tool, made our style guide more work for developers using different tools to use.

Luckily, when it comes to python, all of these problems have already been solved by Black.

Introducing Black

Black was created in 2018 and is described as “The uncompromising Python code formatter”.

🖤

Black is an opinionated, code-formatting tool based on the common Pep-8 style guide. While Pep-8 and many of the tools for checking Pep-8 compliance like pycodestyle or flake8 are excellent for verifying adherence to the Pep-8 guidelines, Black is a code-formatter, and will automatically update your code to Black’s style, which is a superset of Pep-8.

Black is the way

There are a handful of reasons why I believe Black is a wise choice for python developers and library maintainers to adopt — even if you don’t buy into all of its style choices.

Black saves time. Black takes all of the opinions out of code formatting. By buying into its well-thought-out style, you no longer need to make any decisions, like “are trailing commas cool?” or “should I increase line lengths?”. You just install Black and run it. Black is deterministic. When using Black you are given very little control over how code should be formatted, unlike other tools that allow huge amounts of customization. This means every time you run black against your code, you get the same output. It also means, that anytime you’re looking at someone else’s code who uses Black, things should instantly feel familiar. Black’s style makes sense. If you look through their documentation, good reasons are given for nearly all of the style choices made — and while I don’t think my python is too shabby, I think the contributors of Black have probably spent more time thinking about these things than I have. Black already has an impressive list of users. While Black is not yet the go-to for the Official Python core team, a number of notable projects are already using Black. For example, pytest, pandas, pipenv, and pillow (yay P’s) are just a subset of Black’s happy users.

Installing and Running

Black required python 3.6+ to run, but it can still be used to reformat Python 2.x code.

Installing Black is as simple as pip install black .

Running Black is just as easy black <target_directory> .

Results

Before Black

After Black

Conclusion

Everyone is more than welcome to have their own opinions when it comes to code formatting. However, if you care about efficiency and effectiveness more than you care about crafting a perfect .pycodestyle file, Black is the way.