Skip to content

4.1. Linting

What is software linting?

Linting involves utilizing a tool to analyze your code for errors and discrepancies against standard coding conventions. Its primary aim is to identify syntax and stylistic issues, along with other potential programming errors that may have been accidentally included.

Why should you use linter tools?

Linters are indispensable in Python development due to several key reasons:

  • Code Quality: They ensure adherence to best coding practices, crucial for teamwork.
  • Readability: By enforcing a consistent style, they enhance the readability of the code.
  • Early Bug Detection: They spot potential bugs early, reducing debugging and testing time.
  • Learning and Improvement: They are great for developers, particularly novices, to learn and adhere to best practices, thus refining their coding skills.

Which tools should you use to lint your code?

Ruff is a fast, modern linting tool that provides instant feedback, essential for efficient development workflows. The main benefit of ruff is its speed that outpaces many other linters, facilitating a quick fix cycle that doesn't hinder workflow. It also enforces a wide range of linting rules for code quality and consistency. There is also a VS Code Extension for ruff you can use to get linting message while you are typing you code.

# ruff installation (one shot)
uv add --group check ruff
# ruff code base linting
uv run ruff src/ tests/

Remember to exclude the .ruff_cache/ directory in your .gitignore file to prevent the cache folder from being committed.

While there are other linting tools like pylint and pyflakes, ruff is highlighted for its speed and comprehensive rule set.

How should you configure your linting tools?

Configure your linting tools within the pyproject.toml file to tailor their checks to your codebase's specific requirements:

[tool.ruff]
# automatic fix when possible
fix = true
# define the default indent width
indent-width = 4
# define the default line length
line-length = 100
# define the default python version
target-version = "py312"

[tool.ruff.lint.per-file-ignores]
# exceptions for docstrings in tests
"tests/*.py" = ["D100", "D103"]

If necessary, you can exclude linting rules either in your pyproject.toml file or inline if they are not relevant for your project:

# ignore the error code F401 for the line below
from abc.xyz import function_name  # noqa: F401

What are the best practices for linting code?

  1. Integrate with Development Workflow: Make linting a staple of your development routine. Set up your IDE or code editor for immediate feedback.
  2. Customize Rules as Needed: Tailor the linting rules to meet your project's unique needs, although default settings are a solid starting point.
  3. Regular Linting Sessions: Promote frequent linting to prevent the accumulation of issues.
  4. Code Reviews and Linting: Use linting reports during code reviews to ensure compliance with coding standards.
  5. Educate Team Members: Ensure everyone understands the value of linting and knows how to use the tools efficiently.
  6. Balance Between Strictness and Flexibility: Enforce rules on error-prone patterns strictly but allow flexibility for personal coding styles, provided they do not compromise code quality.

Linting additional resources