shahar1 commented on code in PR #73359: URL: https://github.com/apache/airflow/pull/73359#discussion_r4054109094
########## AGENTS.md: ########## @@ -134,7 +134,18 @@ 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 longer explanation for genuinely complex or non-obvious logic (e.g. a security check whose threat model isn't apparent), and keep even that as tight as it can be. Over-commenting is noise that ages badly and obscures the code it wraps. +- **Add a comment only when it preserves context that is not readily apparent from the code.** + Explaining a generic purpose does not qualify: `# Log for debugging` above `logging.info(...)`, + `# Validate for safety`, and `# Retry for reliability` add no useful information. + Useful comments record a specific constraint, invariant, compatibility quirk, or tradeoff; + for example, `# Closing the connection clears the request ID, so log first.` is useful + if that constraint actually applies and is not apparent at the call site. + Before adding a comment, identify the misunderstanding or incorrect change it would prevent. + If removing it loses no such context, omit it. Prefer clearer names or structure when they + convey the same information. Do not narrate code, repeat test names, or invent a rationale. + Keep necessary explanations concise and at the source of truth; do not repeat them at each + call site. Judge their value by the context they preserve, not by the number of lines of code + they describe. Review Comment: Thanks for the feedback! I'll try to refine it. Regarding CI checks - not yet, as it is not supported by GitHub Actions for ASF projects. However, once we offload the CI to AWS - we will be able to utilize AI abilities as part of the CI. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
