Repository navigation
Code comments: a guard against new clutter, and issue numbers instead of "booked in todo.md" #744
Description
The September code-comment inventory sampled 80 comment blocks: 80% are good (they explain why, and point somewhere that resolves). So don't mass-rewrite existing comments. A rewrite would touch about 600 files and conflict with every open branch. Fix a comment when you touch its code. The rot that is concentrated in calendar-era leftovers is already tracked in #699 and #700, and every to-do that lived only in a comment is now an issue.
What's left is stopping new clutter:
- Write the rule into
.ai/conventions.mdand the shared "Working with this project" block (Chronicle, Foundry, Draw Steel). New comments say why and point at a stable target: an ADR, a test name, or an issue or PR (#123, orowner/repo#123across repos). Deferred work is writtenTODO(#123)against a real issue. Not in new comments: dispatch IDs (C-…),cordinator/paths, "this PR/slice/dispatch",file:linepointers, and dates used as provenance. - Add a diff-scoped CI guard that checks only added lines, copying the pattern of
tools/check-plugin-isolation.sh, with a self-test. Add the same guard to the Foundry and Draw Steel repos. - Replace the 15 "booked in
.ai/todo.md" comments in Chronicle's code with the issue number. For example,internal/patch/partial_update_contract_test.gomeans Entity image paths are dropped on import and ignored by the update path #613..ai/todo.mdis now a pointer, and each old tracking ID can be found by searching the issues.
Source: reports/coordinator/2026-09-23-docs-inventory/code-comments.md in the Cordinator repo (section 6).
Activity
Cut essay-length comments down to the rule and the reason
keyxmakerx commentedon Sep 25, 2026
Status after #746 and the package PRs (keyxmakerx/Chronicle-Foundry-Module#99, keyxmakerx/Chronicle-Draw-Steel#59, keyxmakerx/dungeon-alchemist-toolkit#20):
.ai/conventions.mdhas a new "Keep Comments Short, and Out of the Past" section, andTODO(#issue)is the TODO format. Chronicle'sCLAUDE.mdComments line says the same, and each package repo'sCLAUDE.mdhas one line on it. The shared "Working with this project" block is unchanged; the rule lives in each repo's conventions instead.TODO(keyxmakerx/Chronicle#613)). The operator also asked for the existing essays to be cut, so the comments were trimmed across all four repos, not only the booked ones.check-plugin-isolation.sh's added-lines pattern, with a self-test. One lesson from this PR for whoever builds it: diff-scoped guards read committed changes only, so run them after committing. Also, a changed trailing comment makes its whole code line look "added".Generated by Claude Code
keyxmakerx commentedon Sep 25, 2026
One gap in #746's comment sweep. It covered
.go,.templ,.js,.css, shell and YAML files, so it skipped theDockerfile. The builder stage there still has a 27-line incident story explaining why git is installed and whysafe.directoryis set (lines 34–60 onmainat ef034a2). The rule it carries fits in three or four lines.Generated by Claude Code
Shorten the longest remaining comment blocks to the rule and the reason
Shorten CLAUDE.md, the conventions and the plugin notes, keeping ever…
Shorten the decisions log to context, decision and consequences
keyxmakerx commentedon Oct 3, 2026
Pre-deploy check: part of this is done on main. The comment rule is written and the old 'booked in todo.md' comments are gone. Still missing: the CI check on added comment lines (in Chronicle, Foundry and Draw Steel repos).
Generated by Claude Code