Code Style Guide and Tools

High-Quality Code: A Shared Understanding

Spending additional time to write high-quality, readable code is crucial for success in software engineering. Clear and easily comprehensible code not only saves time during development but also simplifies onboarding and collaboration.

In case you are interested, we recommend the following reads for improving your code quality.

Why Follow a Code Style Guide?

A shared code style ensures:

  • Uniform and high-quality code that is easier to understand and maintain.
  • Simplified onboarding for new team members.
  • Fewer errors caused by inconsistencies.

To align with industry standards and avoid reinventing the wheel, we adhere to PEP 8 (Python Enhancement Proposal 8).

Tools for Code Style Enforcement

To make following these guidelines easier, we use the following established, production-grade tools.

Black

Code formatter for syntax.

Flake8

Linter for semantics.

isort

Import sorter.

We’ll demonstrate how to install, use, and automate these tools in your terminal and IDE.

Black

Black is a Python code formatter that enforces a consistent style by automatically adjusting your code to match its uncompromising formatting rules. It ensures uniformity and saves time by eliminating manual formatting efforts.

Installation

pip install black

Terminal Usage

Run Black on files or directories:

black --line-length 100 .

To preview changes without modifying files:

black --line-length 100 --check --diff --color .

We recommend setting the line length to 100 for better readability.

Now you can integrate Black into your favorite IDE. We will show you how to do this in VSCode and PyCharm.

  1. Install the Black Formatter extension from Microsoft.
  2. Open Settings.
  3. Enable Editor: Format On Save.
  4. Set Black Formatter as the default formatter.

  1. Install the BlackConnect plugin.

  2. Install blackd via pip.

  3. Run blackd to start the Black server.

  4. Configure PyCharm to use blackd for formatting and enable auto-formatting on file save.

    a) Run Black on file save and refactor. PyCharm BlackConnect

    PyCharm BlackConnect

    b) If you want the plugin to start the blackd connection on IDE startup, make sure to provide the path to your local blackd installation. PyCharm BlackConnect

You can then trigger the black formatting by pressing Alt + Shift + B.

Flake8

Flake8 is a Python linting tool that analyzes code for style guide enforcement, logical errors, and potential bugs. It provides detailed error codes to help maintain code quality and adherence to standards like PEP8.

Installation

pip install flake8

Terminal Usage

Using Flake8 is very similar to using Black. Unlike Black however, Flake8 cannot fix its found issues on its own because semantics are a lot more complex than syntax.

flake8 --max-line-length=100 .

Now you can integrate Flake8 into your IDE.

  1. Install the Flake8 extension from Microsoft.
  2. Flake8 will highlight errors in the code and display error codes when you hover over them. flake8

While PyCharm lacks native support for Flake8, the following resources may help integrate it.

isort

isort is a Python utility that automatically sorts and organizes imports in your code according to defined standards. It improves code readability and maintains consistency by grouping and ordering imports logically.

Installation

pip install isort

Terminal Usage

isort behaves very similar to Black. It can automatically perform adjustments or run in “check-only” mode. To adjust imports automatically, run the following command.

isort .

To check for changes without modifying files:

isort --check-only --diff --color .

Integrate isort into your IDE workflow as follows.

Install the isort extension from Microsoft to automatically sort imports on file save.
While PyCharm doesn’t natively support isort, you can manually configure import settings to align with isort’s behavior. isort
Prev
Contributing Overview
Next
Commit Hooks