From be37192fe9caf90837ffb3f42be08a08107bf6b9 Mon Sep 17 00:00:00 2001 From: daniel-c-harvey Date: Wed, 29 Jul 2026 21:22:37 -0400 Subject: [PATCH] docs: record comment-reduction pass in COMPLETED, add comment conventions to CLAUDE.md --- CLAUDE.md | 10 ++++++++++ docs/COMPLETED.md | 18 +++++++++++++++--- 2 files changed, 25 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 85c890e..c77c9dd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -144,6 +144,16 @@ three-hot-path performance guardrail above — they do not replace it: A by-class `sampler_core` split that would put virtual envelope `tick()`s on the per-voice-per-sample path is exactly the blowout this forbids. +## Comment conventions (Daniel, 2026-07-29 — driving the tree-wide comment-reduction pass) + +Comments carry *why*, and context where non-obvious — never *what* the code already says. + +- File headers stay brief (~5 lines); no titled prose sections inside them. +- Don't restate invariants a directory's own `src/**/CLAUDE.md` already owns — those files are the home for area invariants. +- No wave/ticket/milestone IDs in comments. A one-line "do not reintroduce X" warning is fine without the ticket number. +- Keep: RT-safety, allocation, and threading constraints; SDK facts confirmed by experiment; compressed regression history; format/version-ladder semantics; warnings against a plausible-but-wrong change. +- When unsure whether a comment is load-bearing, keep it. + ## REAPER extension contract (src/app/main.cpp) - Exactly **one** translation unit defines `REAPERAPI_IMPLEMENT` — that is `main.cpp`. Every other `.cpp` includes `reaper_plugin_functions.h` without the define and gets `extern` declarations for the global API function pointers. diff --git a/docs/COMPLETED.md b/docs/COMPLETED.md index 62b1244..3423133 100644 --- a/docs/COMPLETED.md +++ b/docs/COMPLETED.md @@ -3,6 +3,18 @@ Completed milestone entries removed from `PLAN.md`. Each entry preserves its original Goal, Verify, and checklist points with boxes marked done. -This file holds the current (1.x) cycle's landed milestones only. Nothing has -landed in the 1.x cycle yet. For all pre-1.0 (version-0) history, see -`docs/ARCHIVE.md`. +This file holds the current (1.x) cycle's landed milestones only. For all +pre-1.0 (version-0) history, see `docs/ARCHIVE.md`. + +### Comment-reduction pass (tree-wide, twelve parallel tracks) + +Cut source comment volume tree-wide: 209 files changed, net **−6,493** lines. +Comment-only lines went from 15,073 to ~8,671, a **~42% cut** — before the +pass, 37% of all source lines were comment-only. **Zero code drift**, verified +across all 209 files by comparing comment-stripped hashes; the sole +intentional exception (Daniel-approved) is two user-facing error strings in +`src/shell/capture/capture.cpp` that lost internal milestone IDs (`M8`, `M3`, +`M7+`). Build clean, 61/61 ctest pass. Code review surfaced 2 Major + 8 Minor +findings — all content cut that should have survived — and all ten were +remediated and re-gated before merge. Driver: Daniel's instruction — *"Brief +concise engineering comments. A little why, and maybe context, never WHAT."*