Code Metrics

There are several metrics that measure the quality of our code. Among the main ones (not already discussed) are:

• Size Metrics:
  • Lines of Code (LOC): total number of lines in a source file, including comments and blank lines. Simple but can be misleading.
  • Logical Lines of Code (LLOC or SLOC - Logical/Source Lines of Code): number of lines that actually contain executable code or declarations, excluding comments and blank lines. Generally considered a more significant size measure than LOC.
  • Number of Files, Classes, Functions/Methods: structural measures that give an idea of the project’s granularity and organization.
• Complexity Metrics:
  • Cyclomatic Complexity (CC): measures control flow complexity by counting linearly independent paths. High values indicate code that is harder to test and understand (as previously discussed).
  • Nesting Depth: Measures how deeply control structures (if, for, while) are nested. Deep nesting makes code difficult to follow.
  • Halstead Metrics: a set of metrics (volume, difficulty, effort) based on the number of unique and total operators and operands in the code. They attempt to quantify computational complexity and the mental effort needed to understand the code.
  • Cognitive Complexity: a more modern metric (popularized by SonarSource) that tries to measure how difficult it is for a human to understand the code’s flow, penalizing interruptions in the linear flow (e.g., loops, conditions) and nesting.
• Maintainability Metrics:
  • Maintainability Index (MI): a composite metric that typically combines Cyclomatic Complexity, Halstead metrics (Volume), and Lines of Code (LOC or SLOC) to produce a single value indicating the (presumed) ease of code maintenance. Often scaled from 0 to 100, where higher values indicate better maintainability.
• Coupling and Cohesion Metrics (More advanced):
  • Coupling: measures the degree of interdependence between different modules. Low coupling is desirable.
  • Cohesion: measures how closely related the responsibilities within a single module are. High cohesion is desirable.

A Python package called radon is the main tool for calculating them. There’s also a variant, an abstraction of the latter, used in CI/CD pipelines. It allows setting code quality thresholds that, if not met, cause the program to terminate with an error code, thus failing the build pipeline and ensuring that code in production meets minimum quality standards.

To install it, simply run pip install radon.

Let’s look at the main Radon commands:

• Cyclomatic complexity:

radon cc . -a # Print out all blocks and also the general mark
radon cc . -nb -a # Print out only blocks with mark B or below (the blocks to watch out for)
radon cc . -nb -a --json # JSON output

• Maintainability Index:

radon mi .
radon mi . -nb # Print out only blocks with mark B or below
radon mi . -nb --json # JSON output

• Halstead Metrics:

radon hal .

• Raw Metrics (LOC, LLOC, …):

radon raw .

Coding Standards with Flake8

Maintaining a consistent coding standard is fundamental in Python development to ensure readability, maintainability, and effective collaboration within teams. The official style guide, PEP 8, defines recommended conventions for formatting, naming, and code structure. Flake8 is an extremely popular and powerful tool designed precisely to help developers adhere to these standards automatically. It acts as a “wrapper,” combining the verification capabilities of PyFlakes (which detects logical errors like undefined variables or unused imports), the style checks of pycodestyle (which verifies PEP 8 compliance), and cyclomatic complexity measurement via the McCabe plugin. By using Flake8, you can easily integrate the identification of style violations and common errors into your workflow, thereby promoting the writing of cleaner, more consistent, and high-quality Python code.

Install it simply with pip install flake8.

Flake8 looks for configuration in these files, in order of priority (the first one found is used):

1. setup.cfg (in the [flake8] section) - Often preferred in modern projects.
2. tox.ini (in the [flake8] section) - Common if you use tox.
3. .flake8 (in the project root) - Simple dedicated file.

An example, and an excellent starting configuration, of the pyproject.toml configuration file (or other config files) with parameters for Flake8 is as follows:

# Example for pyproject.toml
[tool.flake8]
ignore = "E203, W503" # E203: whitespace before ':', W503: line break before binary operator
max-line-length = 88
max-complexity = 12
exclude = [
    ".git",
    "__pycache__",
    "build",
    "dist",
    "venv"
]
per-file-ignores = [
    "__init__.py:F401" # F401: module imported but unused (common in __init__.py)
]

(Note: corrected the TOML array syntax for exclude and per-file-ignores)

If you are using Poetry, and therefore have the pyproject.toml file, the section dedicated to Flake8 must be named: [tool.flake8].

Once the main parameters are set in your chosen file (be it .ini, .toml, or .flake8), simply run the flake8 command on the entire folder to get the result.

To get the output in JSON format, however, you need to have the appropriate plugin installed:

pip install flake8-json

At this point, we can run the command, and that’s it:

flake8 . --format=json > flake8_report.json

For a human-friendly output, just remove the format option:

flake8 .

Tests should be divided into two categories: mandatory tests required for pushing to the branch, and optional tests that are useful for generating statistics or additional insights but are not strictly mandatory (e.g., coverage).