Formatting your code
One key insight from the Python programming language is that code is read more often than it is written. Hence, writing code in a fashion that makes it easy to read is something that can only be beneficial.
But formatting code is a nit-picky and tedious matter, isn't it? Moreover, code style is one of those things that are not substantive enough to engage in flame wars. It really is one of those things we should just get over with, right?
Yes, and it is possible to be "just over and done with it" if we use automation tools to help us take care of code formatting so that we don't have to think about it.
Introducing black
black
is an opinionated code formatter for the Python programming language.
It comes with sane defaults,
and produces consistently formatted code with a single command at the terminal.
Installing black
To install it, we can either use pip
or conda
:
# for pip users
pip install black
# for conda users
conda install black
Using black
We can use black directly at the command line in our project directory, with configurations called at the command line for convenience.
# Format all .py files within and underneath current working directory.
black -l 79 .
Introducing isort
isort
is a package for sorting your imports in a source .py
file.
Once again, this is the sort of thing
you definitely don't want to do by hand.
Installing isort
isort
is also conda- and pip-installable.
# pip users
pip install isort
# conda users
conda install isort
Using isort
Just like with black, we can use isort
to automagically sort our imports.
As an example we will call it at the command line with certain options enabled.
# -r: recurses down below the current working directory.
# -y: automatically overwrite original source file with sorted imports.
isort -r -y .
Building automation for code formatting
Automatically executing automagic commands is pretty awesome. Let's see how we can enable this.
Makefiles
I also place black
as part of a series of commands used in code style checking
in a Makefile, to run all of those commands together.
format:
isort -r -y .
black -l 79 .
With that Makefile command, we can now execute all code formatting commands with a single call.
Side note: I usually do isort
first
because black
will make detect isort
-ed code as not properly formatted,
hence I defer to black
to make the final changes.
Pre-commit hooks
We can also use pre-commit hooks to catch non-properly-formatted code, and run the code formatters over the code, preventing them from being merged if any formatting has to take place. This ensures thatwe never commit code that is incorrectly formatted.
Getting set up with pre-commit hooks is another topic, but there are already great resources that can be searched for online on how to get setup.
Concluding words
I hope this short essay gives you an overview of the tools that you can use to format your code automatically. Code formatting is important for readability, but isn't worth the tedium. Letting automation save your time is the wise thing to do.