This is an automated email from the ASF dual-hosted git repository.
kaxil pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 826999928ae Add agent guidance to comment sparingly (#68640)
826999928ae is described below
commit 826999928aea435390799ff5f22895eda0b4fb9e
Author: Shahar Epstein <[email protected]>
AuthorDate: Tue Jun 16 23:51:07 2026 +0300
Add agent guidance to comment sparingly (#68640)
AI-assisted contributions frequently over-comment: multi-line prose
narrating one-line changes, the same rationale duplicated across call
sites, and explanatory comments on tests whose names already convey
intent. The existing review checklist only caught the narrowest case
(a comment restating the very next line), and the write-time coding
standards said nothing at all, so agents had no rule steering them away
from the pattern in the first place.
Add a coding standard directing contributors to comment sparingly and
broaden the review signal so reviewers can flag the wider family of
over-commenting, not just line-restating narration.
---
.github/instructions/code-review.instructions.md | 2 +-
AGENTS.md | 1 +
2 files changed, 2 insertions(+), 1 deletion(-)
diff --git a/.github/instructions/code-review.instructions.md
b/.github/instructions/code-review.instructions.md
index bef87139626..08eec81085d 100644
--- a/.github/instructions/code-review.instructions.md
+++ b/.github/instructions/code-review.instructions.md
@@ -65,7 +65,7 @@ Flag these patterns that indicate low-quality AI-generated
contributions:
- **Description doesn't match code**: PR description describes something
different from what the code actually does.
- **No evidence of testing**: Claims of fixes without test evidence, or author
admitting they cannot run the test suite.
- **Over-engineered solutions**: Adding caching layers, complex locking, or
benchmark scripts for problems that don't exist or are misunderstood.
-- **Narrating comments**: Comments that restate what the next line does (e.g.,
`# Add the item to the list` before `list.append(item)`).
+- **Narrating or redundant comments**: Comments that restate what the next
line does (e.g., `# Add the item to the list` before `list.append(item)`);
multi-line prose explaining a one-line change; the same rationale repeated at
several sites; or explanatory comments on tests whose names already convey
intent. Comments should explain *why* when it is non-obvious, not narrate
*what*. Flag over-commenting as noise to be trimmed.
- **Empty PR descriptions**: PRs with just the template filled in and no
actual description of the changes.
## Quality Signals to Check
diff --git a/AGENTS.md b/AGENTS.md
index 0049d937a2d..4f8b4a37d44 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -134,6 +134,7 @@ reported as such are described in "What is NOT considered a
security vulnerabili
- **Always format and check Python files with ruff immediately after writing
or editing them:** `uv run ruff format <file_path>` and `uv run ruff check
--fix <file_path>`. Do this for every Python file you create or modify, before
moving on to the next step.
- No `assert` in production code.
+- **Comment sparingly — code says *what*, comments say *why*.** Add a comment
only when the reasoning is non-obvious and cannot be carried by a clear name or
the code itself. Do not write narrating comments that restate the next line, do
not pad logic with multi-line prose, and do not repeat the same rationale at
several sites — put one concise note at the source of truth and let the others
stand on their own. Tests whose names already describe intent need no
explanatory comment. Reserve [...]
- `time.monotonic()` for durations, not `time.time()`.
- In `airflow-core`, functions with a `session` parameter must not call
`session.commit()`. Use keyword-only `session` parameters.
- Imports at top of file. Valid exceptions: circular imports, lazy loading for
worker isolation, `TYPE_CHECKING` blocks.
