From e31956a6c1b4b639894fcd49629a4b4f9322be92 Mon Sep 17 00:00:00 2001 From: perf-bundle Date: Wed, 9 Sep 2026 15:10:11 +0200 Subject: [PATCH] Clarify code comment guidance Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: ecc1ebf5-5931-4601-b5d2-9842941da24d --- .github/instructions/NoBloat.instructions.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/instructions/NoBloat.instructions.md b/.github/instructions/NoBloat.instructions.md index c80ca85f01b..b058ba2d4c0 100644 --- a/.github/instructions/NoBloat.instructions.md +++ b/.github/instructions/NoBloat.instructions.md @@ -13,6 +13,8 @@ Reviewers read code, not prose. Add bytes only when they pay for themselves. ## Comments +Write comments for the future maintainer modifying accepted code, not for the reviewer deciding whether to accept the change. If a comment only defends the change, delete it or move that rationale to the PR. It should still be useful a year from now to someone who never saw the diff. + Good names **always** beat comments. Before writing a comment, ask: *can I rename a value, extract a function, or use an active pattern so the comment becomes unnecessary?* If yes, do that instead. - **Do not** restate what the code says (variable name, type name, attribute name, function signature). @@ -20,6 +22,7 @@ Good names **always** beat comments. Before writing a comment, ask: *can I renam - **Do not** justify design decisions inline ("we chose X over Y because…"). Put rationale in the commit message or PR body. - **Do not** leave war-story comments ("previously we did Z, but…", "counter-example: …"). The history is in `git log`. - **Do not** write multi-line `///` doc comments for internal helpers whose body is one expression. +- Treat a moved comment as a new claim: re-check it against the code instead of trusting the prose that travelled with it. Acceptable comments answer **why**, not **what**, and only when the *why* is non-obvious and cannot be expressed by renaming: - Workarounds for compiler/runtime bugs (link the bug).