From abc751fd1c8d58b3bb95a9b6f6fb2a55878b7292 Mon Sep 17 00:00:00 2001 From: Joost Lekkerkerker Date: Mon, 15 Jun 2026 15:48:02 +0200 Subject: [PATCH] Update agents to avoid useless comments (#173523) Co-authored-by: Franck Nijhof Co-authored-by: Ariel Ebersberger <31776703+justanotherariel@users.noreply.github.com> Co-authored-by: Franck Nijhof Co-authored-by: Ariel Ebersberger --- .github/copilot-instructions.md | 4 +++- AGENTS.md | 3 ++- script/gen_copilot_instructions.py | 1 + 3 files changed, 6 insertions(+), 2 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 96cc8f2e4cbc..44781c419005 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -6,6 +6,7 @@ - Start review comments with a short, one-sentence summary of the suggested fix. - Do not comment on code style, formatting or linting issues. +- Flag comments that over-explain straightforward code, narrate the obvious, or read like AI commentary (multi-sentence justifications for a single line). - A Pull Request with a dependency version bump should only contain changes required for the version bump. If the PR includes other changes, request that they are removed from the PR. # GitHub Copilot & Claude Code Instructions @@ -50,4 +51,5 @@ This repository contains the core of Home Assistant, a Python 3 based home autom - Integrations with Platinum or Gold level in the Integration Quality Scale reflect a high standard of code quality and maintainability. When looking for examples of something, these are good places to start. The level is indicated in the manifest.json of the integration. - When reviewing entity actions, do not suggest extra defensive checks for input fields that are already validated by Home Assistant's service/action schemas and entity selection filters. Suggest additional guards only when data bypasses those validators or is transformed into a less-safe form. - When validation guarantees a dict key exists, prefer direct key access (`data["key"]`) instead of `.get("key")` so contract violations are surfaced instead of silently masked. -- Do not add comments that just restate the code on the following line(s) (e.g. `# Check if initialized` above `if self.initialized:`). Comments should only explain why — non-obvious constraints, surprising behavior, or workarounds — never what. +- Keep comments concise. Prefer one short line stating the non-obvious constraint, or no comment at all. +- Do not add comments that just restate the code on the following line(s) (e.g. `# Check if initialized` above `if self.initialized:`). Comments should only explain why (non-obvious constraints, surprising behavior, or workarounds), never what. Never add comments that justify a change by referencing what the code looked like before. diff --git a/AGENTS.md b/AGENTS.md index c6d00025cb4b..e2e8ccb0c52e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,4 +40,5 @@ This repository contains the core of Home Assistant, a Python 3 based home autom - Integrations with Platinum or Gold level in the Integration Quality Scale reflect a high standard of code quality and maintainability. When looking for examples of something, these are good places to start. The level is indicated in the manifest.json of the integration. - When reviewing entity actions, do not suggest extra defensive checks for input fields that are already validated by Home Assistant's service/action schemas and entity selection filters. Suggest additional guards only when data bypasses those validators or is transformed into a less-safe form. - When validation guarantees a dict key exists, prefer direct key access (`data["key"]`) instead of `.get("key")` so contract violations are surfaced instead of silently masked. -- Do not add comments that just restate the code on the following line(s) (e.g. `# Check if initialized` above `if self.initialized:`). Comments should only explain why — non-obvious constraints, surprising behavior, or workarounds — never what. +- Keep comments concise. Prefer one short line stating the non-obvious constraint, or no comment at all. +- Do not add comments that just restate the code on the following line(s) (e.g. `# Check if initialized` above `if self.initialized:`). Comments should only explain why (non-obvious constraints, surprising behavior, or workarounds), never what. Never add comments that justify a change by referencing what the code looked like before. diff --git a/script/gen_copilot_instructions.py b/script/gen_copilot_instructions.py index 51d4995bce69..3e118479b69b 100755 --- a/script/gen_copilot_instructions.py +++ b/script/gen_copilot_instructions.py @@ -23,6 +23,7 @@ COPILOT_SPECIFIC_INSTRUCTIONS = """ - Start review comments with a short, one-sentence summary of the suggested fix. - Do not comment on code style, formatting or linting issues. +- Flag comments that over-explain straightforward code, narrate the obvious, or read like AI commentary (multi-sentence justifications for a single line). - A Pull Request with a dependency version bump should only contain changes required for the version bump. If the PR includes other changes, request that they are removed from the PR. """