exactlyfuriousexpert - Tumblr blog

[exactlyfuriousexpert]

Code formatting in Python - with Black

This week we interview a key maintainer of the uncompromising Python formatter... Black. We gain insight into why Black is designed the way it is from maintainer: Jelle Zijlstra. And an answer to the question, “Why was Black made?” by Łukasz Langa (the creator of Black).

But a quick detour...

Guido van Rossum, the creator of the Python programming language once said:

“Code is read more often than it is written”

There have been numerous attempts to automate the process of formatting code to quality standards but many lack simplicity and effectiveness. They all strive to match the expectations of PEP 8 and beyond. One outstanding automatic code formatter is Black.

And we’re back...

Black. The uncompromising Python code formatter. Black was released to the public for the first time on the 14th of March 2018 and has been used by global companies to format their code ever since. One key feature of Black was that it had no configurability: either agree to the code that Black gave you or... use something else. Now I share with you snippets of my interview with Jelle Zijlstra.

Why did you contribute to Black?

“My first contribution was in May 2018. I first learned about it because Łukasz who wrote it gave a talk about it a local Python meetup. I thought it was an interesting project so I took a look and came with some ideas for how to improve it. Then he made me into a maintainer and now I mostly just review pull requests/issues!”

Which of your original ideas got rejected? Why?

“One we had to back out later because it didn’t work well in practice was numeric underscores. Python lets you write 1_000_000 to make long numbers more readable. I made it so Black automatically inserted those underscores. But we got a lot of complaints because it turns out in real codebases a lot of big numbers are IDs like user IDs, and underscores make them harder to find.”

How do you think the Python programming world views Black?

“At the last in-person PyCon, Łukasz and I had a poster session on Black, which was great because it was mostly just people coming up to us and telling us how great Black is.... and a few complaining about some aspect of how it formats code.”

Why was Black made to be “unconfigurable”?

“Unconfigurability is important because discussions about how to format code are a waste of time. At Black we make all of those decisions for you so you don't have to worry about them. They might not always be all the decisions you agree with, but at least you don’t spend effort on it. There are many aspects of code quality that are harder to get right and that Black can't help you with: good naming, good code organization, etc. Focus on those aspects of code quality as you don't have to consider every detail of formatting.”

Why should we use Black and not some other formatter?

“Honestly I haven’t used other auto-formatters much but there’s a few things that I like about Black that I think are uncommon”:

“Lack of configurability (as discussed)”

“Attempt to give the same formatting no matter how the input is formatted, so code always looks the same. We've compromised on this with the magic trailing comma feature though”

“The AST safety check, which ensures that Black-formatted code doesn't change the meaning of the code. With Prettier in TypeScript I've seen it output code with a syntax error; Black has checks in place that make sure it never does that”

Any advice for budding Black contributors?

“I'd recommend starting with something that doesn't change formatting output (e.g. docs, integrations). We're pretty hesitant to change formatting because there's so much Black-formatted code already out there, and it's disruptive to our users if we change how Black formats code. There's a few areas we know we want to change (search for the "accepted" label on GitHub), but mostly we want to keep the formatting style the same.”

Why was Black made?

Answered by Łukasz himself

“At the time I was working for Facebook on their internal use of Python. There were over 20 million lines of code maintained and too much time during code review was wasted fighting over formatting. Plus different projects ended up having muuuch different coding styles, including some ex-Googlers forcing use of 2-spaced indents in their favorite projects. It was a mess.”

“At first I tried adopting an existing code formatter, YAPF. I even contributed fixes to it and a new style that was more in line with what we wanted at Facebook at the time. However, we couldn't make it work for our 20 million lines of code. It was very configurable but also very inconsistent because of it. I can go into details but in the end it turned out the tool just can't be forced to do what we want because of its design.”

“So I started working on my own. "How hard can it be?" Well, it took me 6 weeks to get to the first alpha release. When I put it out on March 14th 2018 (Pi Day!), it got 500 GitHub stars in one day, Kenneth Reitz started using it right away and tweeted about it, and soon after we got pretty big adoption.”

Whenever you code in Python...

$ pip install black

See you next time!