From cfbc4e4284e7db93d434922ce75a07e64b44d356 Mon Sep 17 00:00:00 2001 From: Jaroslav Bachorik Date: Fri, 30 Oct 2026 13:52:45 +0100 Subject: [PATCH] Add a comment-budget gate to the development guidelines Style rules ('lean', 'state each fact once') are review criteria that only fire on self-re-judgment; agents skip them on fresh sessions. Add a mechanical gate of the kind that already works in this file (the LOC limits): <=3 lines per comment, one distinct constraint per line, prune pass anchored to the finish step, per-line justification required beyond the budget. --- AGENTS.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 3cc8ca4f8d..fec4357392 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -423,6 +423,15 @@ exception list. to an adjacent check is dead; remove it, or keep it only as a deliberate defensive guard whose comment does not claim it catches a distinct case; add duplicated fast-path variants (e.g. `JavaCritical_*`) only for demonstrably performance-critical methods. +- **Comment budget (mechanical gate).** Before finishing any change, run a prune pass + over every comment and javadoc you wrote: each comment ≤3 lines, and each line must + state a distinct constraint (a non-obvious mechanism, invariant, or consequence) that + the reader could not get from the code. A comment that needs more than 3 lines + requires per-line justification in the task summary. Prefer spending the effort on + cutting — a verbose comment is review surface, not safety. The same cut applies to + paragraphs in `doc/` pages and PR descriptions: fewer sentences that each carry a + fact beat more sentences that carry emphasis. This gate complements the comment + rules above; it does not replace them. - Comments: "why" comments must reference concrete mechanisms (e.g. "ASAN's allocator lock is reentrant"), never speculative claims about HotSpot/glibc/ASAN/ISA internals — if unsure, describe the observable symptom. Describe current behavior, not history; cite no