docs: expand contribution guidelines for linting exceptions (#2101)

# What does this PR do?

- Clarified best practices for using `# noqa` and `# type: ignore`,
requiring justification comments
- Improved formatting for readability

Signed-off-by: Sébastien Han <seb@redhat.com>
This commit is contained in:
Sébastien Han 2025-05-05 11:36:30 +02:00 committed by GitHub
parent 1fbda6bfaa
commit a4247ce0a8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -141,11 +141,18 @@ uv sync
## Coding Style ## Coding Style
* Comments should provide meaningful insights into the code. Avoid filler comments that simply describe the next step, as they create unnecessary clutter, same goes for docstrings. * Comments should provide meaningful insights into the code. Avoid filler comments that simply
* Prefer comments to clarify surprising behavior and/or relationships between parts of the code rather than explain what the next line of code does. describe the next step, as they create unnecessary clutter, same goes for docstrings.
* Catching exceptions, prefer using a specific exception type rather than a broad catch-all like `Exception`. * Prefer comments to clarify surprising behavior and/or relationships between parts of the code
rather than explain what the next line of code does.
* Catching exceptions, prefer using a specific exception type rather than a broad catch-all like
`Exception`.
* Error messages should be prefixed with "Failed to ..." * Error messages should be prefixed with "Failed to ..."
* 4 spaces for indentation rather than tabs * 4 spaces for indentation rather than tab
* When using `# noqa` to suppress a style or linter warning, include a comment explaining the
justification for bypassing the check.
* When using `# type: ignore` to suppress a mypy warning, include a comment explaining the
justification for bypassing the check.
## Common Tasks ## Common Tasks