Code formatting is a never-ending topic of discussion for developers. As a project grows bigger and extends over time, the number of contributors to the project increases. As there are different pieces of code worked on by different developers, it becomes very hard to keep the readability of the code consistent.
In our organization, my team and I faced the same situation. We wanted a solution that kept our Python code consistent in the entire repository. Even though we have a style guide, like PEP 8, to tell us how to address the formatting, it was hard for our developers to remember to format the code every time they made a commit. Also, it improves productivity to format code each time it is committed to the repository. For this reason, we started thinking about the concept of using code formatters. We began by listing out the three formatters we considered— AutoPEP8, YAPF and Black.
While discussing the pros and cons of each, we started by comparing Black and AutoPEP8. Although both follow PEP8 coding standards, Black follows better practices. For instance, AutoPEP8 doesn’t format the code if it already follows PEP8 coding standards; whereas, Black decides whether to normalize string quotes/prefixes and can be used to stop managing uniformity of coding styles manually. After eliminating AutoPEP8 from our options, it was time to decide between Black and YAPF. When YAPF was applied twice on the same file (reformatting applied on an already formatted file), it would give inconsistent results. It would obviously be undesirable to have the second formatted file be different from the first time it was formatted. Black, however, produced consistent results even when we formatted previously formatted files multiple times. Black was the clear winner with its better design in reformatting the entire file. Therefore, we decided to use Black for our projects.
Currently, by using Black each time a developer has made changes to their code and wants to commit, he or she does not have to go through every line of code formatting it. They just run Black on the file or on any folder with multiple files, and it will take care of the formatting. To make the process even easier and simpler, providing time-savings (being a repetitive process that needs to be run for every code commit), we decided to automate the entire process. Using Git for version control in our projects, we wanted to use hooks, which is a useful concept in Git, to ease the formatting process. Out of all hooks available, the pre-commit hook feature suited our needs. The pre-commit hook lets you determine set of activities for Git to perform before the developer commits the code. If we attached Black to it, every time a developer commits to our repository, the pre-commit hook automatically runs Black on it, and it lists the files in which the changes are made. Once the developer is satisfied with the changes, he can push the code to the repository.
Black can also be used to format your local project files in addition to an entire repository. Let’s say you want to play and test Black in your local, before you make it as a standard practice with your team, you can pip install it in your virtual environment. And, you will have Black command line interface (CLI) to play with. Below are the instructions to install Black in your local virtual environment:
To run on a single file: ”” black filename.py”” To run on a single folder: “”black foldername/””
Steps to set up black as pre-commit hooks:
Note: Black requires python3.6
- Create a virtual environment and activate it.
- Run the commands below to install black and pre-commit in the environment.
pip install black pip install pre-commit
3. Create a config file for the pre-commit hooks named “.pre-commit-config.yaml” with the below settings
repos: -repo: https://github.com/ambv/black rev: 19.3b0 Hooks: -Id: black
4. Run the pre-commit install to setup precommit hooks for the repo
pre-commit install –config [path to the config file]
Now the setup is complete.
5. Try doing a commit. If Black is installed correctly, it will make changes to the files and list all the files changed.
Installing Black using these instructions is simple and easy to follow. You will only need to setup Black once—the first time you clone the repository. Using this process, we are utilizing Black to format all the Python files in our projects. Over time, we are planning to extend it to our JavaScript project files as well. In this way, we can save time by extending the same code formatter rather than having to search, install, and implement a new one.
We will talk about code formatters for other programming languages in a future blog.
Additional Resources:
- To learn more about Black or pre-commit hooks, check out these urls:
https://black.readthedocs.io/en/stable/installation_and_usage.html
- Hooks can also be used to do other actions like catching AWS passwords, and format JavaScript code. To learn more, go to: https://github.com/pre-commit/pre-commit-hooks
Tags: Technology