From 707fb9b0674eb0f922ae621a8ec7c7ebc4c5d76a Mon Sep 17 00:00:00 2001 From: Carlo van Driesten Date: Wed, 11 Nov 2026 11:13:51 +0100 Subject: [PATCH] docs: align the comment standard across AGENTS.md and CLAUDE.md The two instruction files are byte-identical except for one line, and that line is a contradiction rather than a Claude-specific tweak. AGENTS.md asked for comments that explain invariants; CLAUDE.md banned them by default with a hard one-line cap and an explicit list of banned forms. Agents load one file or the other depending on the tool, so the same codebase was being written to two different standards, and neither copy said the other existed. This adopts the stricter rule in both, because it is the one written for this codebase and the one the recent code follows. --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 831f7d7401..64a509a358 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,7 +20,7 @@ Activate venv before `python`/`puffer`: `source .venv/bin/activate` - **Data:** flat struct arrays + integer indices. No nested ownership / `**` unless the map/grid truly needs it. - **Loops bounded:** iterate known counts; every `while` needs an explicit max-iteration counter. - **Named constants for all magic values** (`GRID_CELL_SIZE`, `DEFAULT_TTC`); never raw `15.0f`/`64` in logic. Centralize enum-like mode constants near the top. -- **Comments explain invariants, not syntax** (good: "reward flags mutually exclusive"). Code readable without comments. +- **Comments: default none, hard max 1 line.** Code must be readable without them. Write one only for a non-obvious invariant, unit/frame convention, or a "why not the obvious thing" (good: `// reward flags mutually exclusive`, `// angles in ego frame, radians`). Banned: restating what the line does, multi-line explanations, rationale/history essays, cross-file pointers (`// see drive.h`), section headers (`// 1. Encoders`), docstrings on self-evident functions. If it needs a paragraph, rename things until it doesn't. Never add a comment to a line the request didn't already change. - **Check non-void returns when correctness depends on it** (loading, init, map/grid build, spawning). - **Zero compiler warnings** — warnings are bugs until proven otherwise. - **Perf:** zero Python overhead in C hot paths; no malloc/free in `c_step`, obs gen, collision, reward.