.. _code-quality:

****************************************************
Code Quality
****************************************************

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

~~~~~~~~~~~~
Black
~~~~~~~~~~~~

`Black <https://github.com/psf/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 <https://github.com/pre-commit/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.


~~~~~~~~~~~~
Flake8
~~~~~~~~~~~~

`Flake8 <https://github.com/PyCQA/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 <http://flake8.pycqa.org/en/latest/user/error-codes.html>`__
or also by checking `this link <https://lintlyci.github.io/Flake8Rules/#pyflakes>`__. 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**.

~~~~~~~~~~~~
Djhtml
~~~~~~~~~~~~
Used for properly **indenting** django templates automatically. You can find out more about it
`here <https://github.com/rtts/djhtml>`__

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

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 :code:`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 :code:`pre-commit install --install-hooks`. That's all,
pre-commit will take care of installing the packages and running them on every commit.

3. For `integrating Black with Pycharm <https://github.com/psf/black#pycharmintellij-idea>`__:

    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$

4. 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.