From 72445c4d2f2e8820d697cab9f7bcc8f88f72b85d Mon Sep 17 00:00:00 2001 From: kolaente Date: Thu, 4 Jun 2026 22:48:03 +0200 Subject: [PATCH] docs(agents): comments should document the why, not the what Adds a Code Style bullet: default to no comment; only document a non-obvious why (gotcha, invariant, rejected alternative) in one tight line; cut comments that restate the code, a name, or a signature. --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 9eff785d0..d53e082c5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -273,6 +273,7 @@ After adjusting the source string, you need to call the respective translation l - Go: golangci-lint per `.golangci.yml`; use goimports; wrap errors with `fmt.Errorf("...: %w", err)`; enforce permissions checks in models; never log secrets; do not edit generated `pkg/swagger/*` - Vue: ESLint + TS; single quotes, trailing commas, no semicolons, tab indent; script setup + lang ts; keep services/models in sync with backend - Follow existing patterns for consistency +- **Comments: document the *why*, not the *what* — default to no comment.** Don't write comments that restate the code, a function/struct/field name, or a signature; they're noise the reader skips past (a comment that takes longer to read than the code it describes should be deleted). Only comment a genuinely non-obvious *why* — a gotcha, an invariant, a rejected alternative, a cross-file constraint — in one tight line. Be aggressive about cutting on the first pass, not just when asked. - Before creating a new file, function, or helper, search the codebase (`grep` / `rg`) for existing code that does the same thing. Prefer extending an existing helper over duplicating it. If logic overlaps an existing function significantly, reuse it. **Naming Conventions:**