From a4247ce0a8560cc8ccfce2b8b742111574b93aa4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Han?= Date: Mon, 5 May 2025 11:36:30 +0200 Subject: [PATCH] docs: expand contribution guidelines for linting exceptions (#2101) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # 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 --- CONTRIBUTING.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5828250d0..17eed43c5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -141,11 +141,18 @@ uv sync ## 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. -* 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`. +* 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. +* 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 ..." -* 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