Zaniar Shokati
← Back to writingClean Code

Tools to Enforce Basic Quality Standards

Sep 13, 2023

Understanding Clean Code

Clean code is like a hidden gem in the world of programming. Rather than being defined by strict rules or machine-measurable metrics, clean code represents something developers collectively recognize and value.

Programming languages serve dual purposes: communicating with machines and conveying ideas to fellow developers. The true measure of code quality depends on whether other engineers can effortlessly read and maintain it.

The Significance of Clean Code

1. Maintainability for Agile Success

Think of a well-maintained codebase like a well-maintained car on a road trip — it gets you where you need to go predictably. A clean codebase prevents constant interruptions from technical debt, allowing teams to meet project timelines and incorporate features smoothly.

2. Unpacking Technical Debt

Technical debt functions similarly to financial debt, accumulating "interest" over time. Postponing code improvements increases future costs, as teams must repeatedly halt progress to address underlying issues.

3. Silent Threat Lurking Beneath the Surface

Technical debt operates subtly — it quietly permeates all corners of your project without raising immediate alarms, eventually becoming a major roadblock.

Configuring Tools to Enforce Basic Quality Standards

Code exists for humans to comprehend, making developer judgment essential for evaluating quality. Code reviews should focus on readability and logical structure rather than superficial formatting.

Critical review questions include:

  • Is this code readily understandable and logical for fellow programmers?
  • Does it effectively address the problem domain?
  • Could a newcomer to the team easily grasp and work with this code?

All quality checks should be automated and integrated into continuous integration pipelines, causing builds to fail when standards aren't met.

Code Inspection with Pylint: Elevating Code Quality

Pylint stands out among Python inspection tools for its comprehensiveness and customization options.

Installation

pip install pylint

Running Pylint

pylint your_file.py

Configuration

Through the pylintrc configuration file, developers can:

  • Enable or disable specific rules
  • Parameterize rules (e.g., maximum line length)
  • Align Pylint with project-specific coding standards

Example: Factorial Function

Original code issues:

sample_code.py:12:0: C0304: Final newline missing (missing-final-newline)
sample_code.py:1:0: C0114: Missing module docstring (missing-module-docstring)
sample_code.py:1:0: C0116: Missing function docstring (missing-function-docstring)
sample_code.py:1:14: C0103: Argument name "n" does not conform to snake_case naming style
sample_code.py:2:4: R1705: Unnecessary "elif" after "return"

Your code has been rated at 5.00/10

Corrected code:

"""
A simple function to calculate the factorial of a non-negative integer.
"""

def factorial(value):
    """
    Calculate the factorial of a non-negative integer.

    :param value: The non-negative integer.
    :return: The factorial of value.
    """
    if value < 0:
        return "Invalid input"

    result = 1
    for i in range(1, value + 1):
        result *= i

    return result

if __name__ == "__main__":
    print(factorial(5))

Result:

Your code has been rated at 10.00/10

Key improvements: adding docstrings, consistent indentation, proper spacing around operators, and removing unnecessary conditional structures.

Type Hinting with Mypy

Mypy enables optional static type checking in Python, catching potential bugs early before they reach production.

Installation

pip install mypy

Running Mypy

mypy your_python_file.py

Example: Type Hinting

Without type hints:

def add_numbers(a, b):
    return a + b

result = add_numbers(5, "10")
print(result)

Mypy error:

error: Argument 2 to "add_numbers" has incompatible type "str"; expected "int"
Found 1 error in 1 file

With type hints:

def add_numbers(a: int, b: int) -> int:
    return a + b

result = add_numbers(5, 10)
print(result)

Mypy result:

Success: no issues found in 1 source file

Embrace Code Consistency with Black

Black is an uncompromising Python code formatter that enforces strict, consistent styling.

Benefits of Black

  • Speed: Automates formatting, saving time and mental energy
  • Determinism: Guarantees consistent output regardless of project
  • Freedom from formatting debates: Eliminates discussions about indentation and line length
  • Improved focus: Consistent style becomes transparent, allowing concentration on logic
  • Efficient code reviews: Generates smallest possible diffs, focusing reviews on functional changes

Installation

pip install black

For Jupyter Notebooks:

pip install "black[jupyter]"

From GitHub:

pip install git+https://github.com/psf/black

Basic Usage

black {source_file_or_directory}

Formatted Example

Black applies consistent spacing and structure:

"""
A simple function to calculate the factorial of a non-negative integer.
"""


def factorial(value):
    """
    Calculate the factorial of a non-negative integer.

    :param value: The non-negative integer.
    :return: The factorial of value.
    """
    if value < 0:
        return "Invalid input"

    result = 1
    for i in range(1, value + 1):
        result *= i

    return result


if __name__ == "__main__":
    print(factorial(5))

Elevate Your Testing with Pytest

Pytest is a versatile testing framework suitable for small unit tests through complex functional testing.

Key Advantages

  • Simplicity and readability: Straightforward syntax for expressive test code
  • Scalability: Handles both small and complex testing scenarios
  • Test discovery: Automatically finds tests following naming conventions (e.g., test_ prefix)
  • Fixture support: Manages test setup and teardown resources
  • Extensive plugin ecosystem: Rich collection of plugins for coverage, parallelization, and tool integration

Installation

pip install -U pytest

Example Test

test_sample.py:

def func(x):
    return x + 1

def test_answer():
    assert func(3) == 5

Running tests:

pytest test_sample.py

Failed test output:

plugins: anyio-3.6.2
collected 1 item

test_sample.py F                                                          [100%]

======================================================= FAILURES =======================================================
_____________________________________________________ test_answer ______________________________________________________

    def test_answer():
>       assert func(3) == 5
E       assert 4 == 5
E        +  where 4 = func(3)

test_sample.py:5: AssertionError
=============================================== short test summary info ================================================
FAILED test_sample.py::test_answer - assert 4 == 5
================================================== 1 failed in 0.04s ===================================================

Conclusion

Integrating Pylint, Mypy, Black, and Pytest into your development workflow enforces consistent quality standards automatically. These tools enhance readability, catch errors early, and eliminate time spent on formatting debates — ultimately delivering higher-quality software that your teammates can actually maintain.