3. Code Quality

In order to maintain a good code quality, we use Black for code formatting and flake8 for code linting.

3.1. Black

Black is a code formatter that tries to solve all the discussions around how the code should be formatted by taking control of that:

Black is the uncompromising Python code formatter. By using it, you agree to cede control over minutiae of hand-formatting. In return, Black gives you speed, determinism, and freedom from pycodestyle nagging about formatting. You will save time and mental energy for more important matters.

The main goals for implementing Black is to no longer think about code formatting while writing or reviewing code and make it run automatically on every commit (thanks to pre-commit). That should be possible by having pre-commit execute a hook when committing that runs Black to format the code. For anyone used to having a shortcut do the code formatting, the last step helps in running Black with a shortcut.

3.2. Flake8

Flake8 is a code linter and a wrapper around 3 tools: PyFlakes, pycodestyle and Ned Batchelder’s McCabe script for calculating code complexity. We will only be ignoring pycodestyle warnings because Black takes care of formatting. The warnings generated by flake8 can be found here or also by checking this link. Flake8 will also be run automatically when committing thanks to pre-commit, however, it will block the commit if any warnings are raised and in that case the developer is expected to check the warning and fix before committing.

3.3. Djhtml

Used for properly indenting django templates automatically. You can find out more about it here

In the future we might move to an actual template formatter (one candidate is djlint).

3.4. Steps to setup pre-commit hooks

Pre-requisites:

  • As we run the project using Vagrant, we make the distinction between host-OS (the OS on which Vagrant is installed be it Windows/Ubuntu/MacOS) and guest-OS (the OS running in the vagrant VM which is Ubuntu).

  • It is assumed that python 3.8 is already installed on the host-OS and all requirements for the project are installed in the Vagrant VM.

To set up the code quality tools, make sure to follow these steps.

1. Install pre-commit in your host-OS by running pip install pre-commit. It is important that pre-commit is installed in the host-OS as IDEs use git from the host-OS. So, the git hook that pre-commit adds is executed on the host-OS. That leads us to installing the package on the host-OS.

2. In the project root in your host-OS, run pre-commit install --install-hooks. That’s all, pre-commit will take care of installing the packages and running them on every commit.

  1. For integrating Black with Pycharm:

    File -> Settings -> Tools -> External Tools

    Click the + icon to add a new external tool with the following values:

    Name: Black

    Description: Black is the uncompromising Python code formatter.

    Program: <install_location in the host-OS> example: C:\Users\<user>\AppData\Local\Programs\Python\Python38\Scripts\black.exe

    Arguments: $FilePath$

    Working directory : $ProjectFileDir$

  2. Add black shortcut:

    File -> Settings -> keymap -> External Tools -> External Tools -> Black

    Double-click on Black and click “Add Keyboard Shortcut” to add a new shortcut: Ctrl+Alt+L

    PS: “Ctrl+Alt+L” is the default shortcut for formatting in Pycharm, so by defining this shortcut, it is as if Black is the default code formatter for Pycharm.