From 343f75359234251d7ef79e285233167bd8953327 Mon Sep 17 00:00:00 2001 From: Andy Scherzinger Date: Sun, 9 Aug 2026 21:32:09 +0200 Subject: [PATCH] docs: Add code comment conventions for AI agents to AGENTS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Comments must document the code itself (signatures, behavior, constraints) — never progress, decisions, or changes, which belong in the commit message or PR discussion and go stale in code. Comments must stay brief and match the surrounding comment density. Follow-up to the discussion in #1970. Assisted-by: Claude Code:claude-fable-5 Signed-off-by: Andy Scherzinger --- AGENTS.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 1644e13a9..f5d73ea45 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -76,6 +76,11 @@ There are no PHP unit tests. Two integration test suites exist: ## Conventions +- **Code comments** document the code, never the process that produced it: + - Comments describe what the code does — method signatures, behavior, and constraints the code itself cannot express (e.g. a non-obvious invariant or workaround). + - Never add comments that document progress, decisions, or changes (e.g. "changed X to Y", "as requested", "this fixes ...", "previously this did ..."). That belongs in the commit message or PR discussion; in the code it goes stale and becomes misleading. + - Do not narrate self-explanatory code. If the code is readable without a comment, omit the comment. + - Keep comments brief — short and simple, matching the comment density of the surrounding code. - **Conventional commits** are enforced on PRs by CI (e.g. `fix(l10n): ...`, `feat: ...`). - Every file needs an SPDX license header; CI enforces REUSE compliance. - `l10n/` translation files are synced from Transifex — never edit them manually.