Science and Technology

👁 Photo by Matt Hoffman on Unsplash

Overview of Your Journey

1. Setting the Stage
2. What About Your Trusted Friend, PEP8?
3. What Really Matters
4. Black – The Uncompromising Code Formatter
5. Look how Easy Using Black Is!
6. Is Black the Solution to All Code Quality Problems?
7. Wrapping Up

---

Setting the Stage

We’ve all been there. That moment when one of your colleges brings up code formatting. Watch out! You are about to enter a time-draining discussion.

It turns out that many Python developers have strong opinions on code formatting. So do I. To tackle the topic of code formatting, I want to give you the answers to the following three questions:

• Doesn’t PEP8 dictate the code formatting in Python?
• What is the most important thing about code formatting?
• How can I quickly implement code formatting in a project?

The above questions will take us to Black – The Uncompromising Code Formatter. I will show you how using Black in projects can be an immense time saver. Hence you can spend your time actually writing awesome Python code 😀

If you don’t take my word for it, then the author of SQLAcademy has the following to say about Black:

"I can’t think of any single tool in my entire programming career that has given me a bigger productivity increase by its introduction. I can now do refactorings in about 1% of the keystrokes that it would have taken me previously when we had no way for code to format itself." – Mike Bayer

---

What About Your Trusted Friend, PEP8?

Every Python developer should know PEP8 more or less by heart – it is the official style guide for Python.

As an example, PEP8 prefers to have spaces on each side of the equality sign = in a variable assignment. So don’t write any of the following:

# Ahh! My eyes!
my_variable=5
my_variable =5
my_variable= 5

Instead, you should write:

my_variable = 5

Simple, right? PEP8 has a thing for symmetry.

Yet, the guidelines in PEP8 are not enough to settle all decisions. As an example, consider the list of pokemon:

pokemon = ["Bulbasaur", "Charmander", "Squirtle", "Pikachu"]

The way I wrote the list pokemon above is PEP8-approved. However, so is the following two ways:

# Another acceptible way
pokemon = [
 "Bulbasaur", "Charmander", 
 "Squirtle", "Pikachu"
]

# Yet another one
pokemon = [
 "Bulbasaur", 
 "Charmander", 
 "Squirtle", 
 "Pikachu"
]

Watch out! Subjectivity has entered the chat.

The truth of the matter is that PEP8 allows some flexibility here and there. It is this flexibility that sparks so many time-draining discussions.

Imagine showing the above code to other developers and asking:

Which of the above pokemon lists is the best one? Which one is the most Pythonic?

The following image represents the next thirty minutes of your life 😅

👁 Photo by John Schnobrich on Unsplash

---

What Really Matters

When it comes down to it, the most important thing about formatting code is consistency. Having code that looks the same across the codebase makes it easier to read the code.

The precise formatting choice of the pokemon list earlier is not that important. All three PEP8-approved options I presented are pretty readable. The important thing is that everyone on the project sticks to the same formatting!

Rather than starting an office war over this choice, why not let a third party decide? This is where Black comes into the picture.

---

Black – The Uncompromising Code Formatter

👁 The Official Logo for Black - The Uncompromising Code Formatter

_"_Black is the uncompromising Python code formatter. By using it, you agree to cede control over minutiae of hand-formatting. You will save time and mental energy for more important matters." – The Documentation for Black

Black is a Python module that formats your code in the blink of an eye. No more pointless formatting discussions. Black lets you focus on the important stuff. Dusty Phillips said it best:

"Black is opinionated so you don’t have to be." – Dusty Phillips

If you want to test out Black before committing to it, then you can play around in the Black Playground. You can also check out The Black Code Style to see the code style that Black will enforce on your code.

To get started with Black, you need to download it first. Note that the default version of Black requires Python 3.6.2 or higher. Run the following command in your terminal to install Black:

pip install black

That’s it! You now have Black installed 👊

Fun Fact: Blacks motto is "Any color you like." This is a play on Henry Ford’s famous saying:

"Any customer can have a car painted any colour that he wants so long as it is black." – Henry Ford

Blacks motto alludes to the fact that Black is uncomprimising in its code formatting. This also explains (at least to me) why Black’s logo looks like a car logo.

---

Look how Easy Using Black Is!

👁 Photo by Kasya Shahovskaya on Unsplash

Are you expecting me to start rambling on about various configurations you need to set? Think again! Black comes with the batteries included 😃

---

A Simple Example

The following code snippet is an example of bad code formatting:

Yuck! Rather than fixing the formatting manually, you should let Black do the job. If you are in the folder where the file bad_code_formatting.py resides, then you can run the command:

python -m black bad_code_formatting.py

By doing this, Black should give you the message:

All done! ✨ 🍰 ✨
1 file left unchanged.

Cute. Now the code in bad_code_formatting.py looks like the following:

The filename bad_code_formatting.py is no longer appropriate: The code has been automatically PEP8-formatted. Where PEP8 is flexible, Black has made the choice for how to format the code. No decisions are necessary on your part!

---

Modifying Line Length

The default line length is 88 characters in Black. If you have an employer that pays you for the number of lines written, then you can always run the command:

python -m black --line-length=70 bad_code_formatting.py

The file bad_code_formatting.py now looks like the following:

Other than this, there are few reasons to mess with the default line length that Black gives.

---

Using Black on a Folder

Say you have many Python files in a folder called multiple_python_files. You don’t need to run Black on each file individually. You can instead run Black on the whole folder with the command:

python -m black multiple_python_files

Black has now formatted all the Python files in the folder 😍

---

Is Black the Solution to All Code Quality Problems?

I wish…but no.

It is a mistake to think that Black will fix all code quality problems. For instance, Black will not give your variables descriptive names. Nor will it make poorly written docstrings any better. Black will not introduce type hints to your codebase. Nor will it put in place effective design principles.

Properly formatting bad code is like giving a paint job to a car wreck!

Black should only be one of the tools in your toolbox when thinking about code quality.

---

Wrapping Up

In this blog post, I have advertised Black as a convenient code formatter. The great thing about Black is its uncompromising nature. Unfortunately, there is not much more to say: Black is as simple as it is useful 💜

Another way to improve your code quality is to write type hints. Type hints are a great Python feature that many projects can benefit from. If you are new to type hints, then I have written a blog post on the topic:

Modernize Your Sinful Python Code with Beautiful Type Hints

If you are interested in data science, programming, or anything in between, then feel free to add me on LinkedIn and say hi ✋

Share This Article

• Share on Facebook
• Share on LinkedIn
• Share on X