From 04f3d107b2f828248d44c959942bc1c5d4883048 Mon Sep 17 00:00:00 2001 From: Umberto Sgueglia Date: Wed, 5 Aug 2026 13:03:24 +0200 Subject: [PATCH] feat: enforce default no comments Signed-off-by: Umberto Sgueglia --- CLAUDE.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index e898af8cde..34b6a14258 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -69,4 +69,16 @@ Millions of rows. Every query matters. - Define types properly — extend and reuse existing types. Don't sprinkle `any`. - Don't touch working code outside the scope of the current task. - Prefer doing less over introducing risk. Weigh trade-offs before acting. -- Default to no comments. When one is warranted (non-obvious WHY), keep it to 2 lines max. +- No comments. Code must be self-explanatory: name things well and extract + functions instead of explaining them. +- A comment is allowed ONLY if one of these is true, and the reason cannot be + expressed in code: + - workaround for an external bug/API quirk (link it) + - non-obvious invariant or ordering the caller must respect + - performance/concurrency constraint that looks removable but isn't + - genuinely convoluted logic (e.g. inherited/legacy complexity) that can't + be simplified or extracted right now — prefer refactoring over commenting + - `TODO(CM-XXX):` with a ticket +- Never comment: what the code does, section headers, JSDoc on obvious + functions, notes about the change you just made. +- When allowed: 2 lines max.