In life, it is a good idea to wash regularly, brush your teeth, clean and iron your clothes etc.

In coding, it is much the same. Code hygiene is important! Fortunately, it is pretty easy to implement. In my own work, I have found a few things to go a long way in helping you keep your code and project clean!

Dependencies

Firstly, dependencies. When working with Python, it is good practice to have your project run within a virtual environment or venv (Think of venv as a kind of package.json for Python). This ensure that you do not have global dependency issues with your project and keeps all your project dependencies in one place. In order to set this up for a new project, change into your project directory and run the following from the command line:

Depending on your version of python, run: python -m venv env

This will install the venv into your working directory.

To activate this, you run: source env/bin/activate

In your .gitignore file, be sure to add env/ to since you do not want to include this folder in your repo.

Also, remember to ensure all your dependencies are listed in a requirements.txt file. (See end for an example)

Code Style

Python has many code style guides, and one I have been using is flake8

Effectively, flake8 will ensure that your code is adhering to specific style guides. If you are working in VS Code, you can set this up in your working directory by creating a .vscode folder and adding a settings.json file to it. In that file add the following:

{
    "python.pythonPath": "env/bin/python3.7",
    "python.linting.flake8Enabled": true,
    "python.linting.enabled": true,
}

What this does, is sets your VS Code Python interpreter to the Python version in your venv (be sure to use your specific Python version). Setting both flake8 and linting to true will mean that VS Code will run your code through flake8 and will highlight any deviations from the flake8 rules. VS Code will prompt you to install flake8, if not, you can install via:

python -m pip install flake8

If you need to manage specific flake8 rules, you can set them in a setup.cfg file as follows:

[flake8]
max-line-length = 88

You can also run flake8 directly from the command line via:

flake8 path/to/code

This will then return any deviations via messages in the command line. You can correct them as needed. (If correctly setup, VS Code should highlight these with little red squares in the sidebar indicating where in the file the problems appear)

Formatting

While code style is one thing, formatting is another. A very popular library for this in the Python world is black

As always, you can install via: pip install black

You can also ensure that VS Code assists you in this by adding the relevant line to your settings.json file as follows:

"python.formatting.provider": "black"

From there, to run black you enter:

• To check for any problems only, run: black project --check
• To check what the suggested change will be, run: black project --diff
• To execute the changes run: black project

While your preference may differ, I prefer to make all my commits to repo and then run flake8 and black afterwards. That way, I can double-check the changes from the Git diff viewer in VS Code before commiting them to repo. This helps me ensure I am aware of what the changes are separate of my actual code changes.

Sorting dependencies

Another item that may fall to personal prefernce, but I feel it is a good practice is to sort your imports/dependencies alphebetically. You can use isort for this.

Similar to the other tools above, you can install via: pip install isort

To run the checks, do the following:

• To check for possible changes run: isort path_to_code/*/*.py --check-only
• To check what the suggested changes are, run: isort path_to_code/*/*.py --diff
• To make the changes, run: isort path_to_code/*/*.py

As before, I prefer to run isort after my other changes are already commited so I am sure what is being changed.

Conflicts

In the past, I have run into a conflict betweem black and isort in the way they manage certain rules. This creates a "loop" effect where black changes the import one way, then isort another. In a CI/CD environment this is not ideal to say the least. In any event, there is a solution! You can setup isort to play nice with black by foind the following:

• Create a .isort.cfg file, and in it, add the following code below:
• Depending on your ruleset, this will vary - see this issue for more detail

[settings]
multi_line_output=3
include_trailing_comma=True
force_grid_wrap=0
use_parentheses=True
line_length=88

Ideally, all of this will be wrapped up into a nice Docker environment for development and release... but that is a topic for another time! In the meantime, I am sure your team mates will appreciate the extra care and attention you have paid to your Python hygiene!

Requirements

Make sure to add the following to your requirements.txt file (check for relevant versions):

black==19.3b0
flake8===3.7.8
isort==4.3.21