Formatting and linting

[github-actions[bot]]

It is helpful for reviewers/contributors if you adhere to a standard python style guide. There is a package called ruff that can help you fix up your code to adhere to these.

Install ruff using pip install ruff and then you can run ruff format to automatically format your files against their (black standards, which is aligned with the the most common formatting standards (called black).

You can also run ruff check to help you lint the files.

[DaniBodor]

Linting and formatting are related yet different tasks. I found it hard to explain the difference, so asked ChatGPT, and it gave a great answer:

In Python (and other programming languages), formatting and linting are related to code quality and style, but they serve different purposes:

1. Formatting

Formatting refers to the process of arranging and styling code according to specific rules or conventions. This includes things like indentation, spacing, line length, and other stylistic choices that make code easier to read and maintain. Formatting tools automatically adjust your code to meet these conventions.

Examples of formatting tasks:

• Ensuring consistent indentation (e.g., 4 spaces per indent level).
• Converting quotes (e.g., single quotes to double quotes).
• Wrapping long lines to a maximum line length (e.g., 80 characters).
• Adjusting spacing around operators and keywords.

Popular formatting tools in Python:

• Black: A highly opinionated code formatter that applies a consistent style.
• autopep8: A tool that automatically formats Python code to conform to the PEP 8 style guide.
• YAPF (Yet Another Python Formatter): A formatter from Google that formats code to conform to a specified style.

2. Linting

Linting refers to the process of analyzing code to identify potential errors, bugs, stylistic errors, or other problematic patterns. Linters provide feedback on code quality, adherence to best practices, and can catch potential bugs before the code is run.

Examples of linting tasks:

• Detecting syntax errors or undefined variables.
• Highlighting unused imports or variables.
• Suggesting improvements for code complexity or readability.
• Identifying potential bugs, like type mismatches or logical errors.

Popular linting tools in Python:

• Pylint: A comprehensive linter that checks for errors, enforces coding standards, and suggests refactoring opportunities.
• Flake8: A lightweight linter that checks for PEP 8 compliance and simple errors.
• mypy: A linter for checking type annotations and static type checking.

Key Differences

• Purpose: Formatting focuses on the appearance and consistency of code, while linting focuses on identifying potential errors and enforcing coding standards.
• Functionality: Formatting tools modify code directly, whereas linters analyze code and provide feedback or warnings.
• Output: Formatters rewrite code to match style rules; linters produce reports or messages about code issues without changing the code.

Both formatting and linting are essential for maintaining high-quality, readable, and reliable code.