Repository navigation
Closed
Labels
documentationImprovements or additions to documentationImprovements or additions to documentationtech-debtInternal maintainability or refactoring workInternal maintainability or refactoring work
Description
Part of the code-health epic. Evidence pinned to main @ 71b8c94.
Problem
Comments in src record history rather than explaining the current code:
- There are 2,191
#NNNissue references, about 25 per 1,000 code lines.from_model.pyhas 292 anddrawing.py259. - 142 comments cite review rounds, for example "(Codex ADR 0005 §4 applies to public API too: the #817 deprecations and --style carry no removal date #987 r1)" at
drawing.py:1731and "Codex A placed annotation carries no measurement identity, so two builds cannot be compared reliably #1002 r5" ataudit.py:1171. - There are 514
ADR n (was 00NN)pointers. - Many comments tell the story of a change ("moved here in tech-debt: break the builder / cli / sheet_emit import cycle #523", "was the pre-Consolidation P5: enforce the DAG everywhere — extend import-boundary tests beyond model/; keep the docs matching the territory #640 norm"), and some narrate over several lines (e.g.
drawing.py:1291). - The longest docstrings are
_build_drawing_once(85 lines),SolveTrace(61) andfinalize(56). - Comment and docstring lines are 24% of code lines overall, and 23–28% in
drawing,_common,builderandsheet.
The history belongs in git. It makes the code slower to read, and the comments go stale.
Proposal
- Add a written convention: a comment explains why the code is like this now, and can cite at most one issue, for the invariant it defends. Review-round citations and move history are not allowed.
- Sweep the files module by module, starting with the most-churned ones.
- Change
ADR n (was 00NN)to plainADR ninsrc, and keep the "was" mapping only indocs/adr/. This needs atest_adr_corpuschange, so it is the maintainer's call. - Optional: a ratchet test on the count of
Codex #…andr[0-9]citations insrc.
Progress
- Remove review provenance from source comments (#1934) #1987 merged a first comment/docstring sweep across 38 source files. Fresh review found no executable or API change; the executable AST matched main and the required CI gate passed.
- The historical review-round/Codex patterns scanned in this slice are now absent from
src. Textual#numbermentions fell from 2,169 to 2,124 on its current base. The issue-reference halving criterion remains open. - ADR pointer normalization and the broader history sweep remain to be decided/implemented without changing ADR text.
Acceptance
- No review-round citations remain in
src. - Issue references are cut by at least half.
- The behaviour is unchanged (comments only).
Metadata
Metadata
Assignees
Labels
documentationImprovements or additions to documentationImprovements or additions to documentationtech-debtInternal maintainability or refactoring workInternal maintainability or refactoring work
Activity
Replace from_model comment history with current rationale (#1934) (#1970
pzfreo commentedon Sep 28, 2026
First module slice merged in #1970 (
1ab06071).annotations/from_model.pyPython-comment issue references fell from 178 to 3, and Codex/review-round citations from 17 to 0. The remaining three inline phase comments need behavior tests before changing them because this PR's changed-line coverage gate would otherwise fail; 121 references remain in unchanged docstrings and strings. A written comment convention is now in AGENTS.md. Independent review findings were fixed; AST/literal parity, Ruff, and all CI jobs passed (including changed-line coverage). The whole-source #1934 acceptance remains open.Remove review-round provenance from source comments (#1934)
Remove review provenance from source comments (#1934) (#1987)
docs: explain current declaration boundaries (#1934)
docs: explain current declaration boundaries (#1934)
docs: explain current declaration boundaries (#1934)
docs: explain current declaration boundaries (#1934)
Integrate reviewed code-health slices with one CI gate (#1939) (#2102)
pzfreo commentedon Sep 29, 2026
Completed in #2102. On the same tokenizer scan, source-comment issue references fell from 999 on pre-merge main at 63cb9fe to 467 on merged main at 502bbc4 (below half); review-round/Codex citation matches are zero. The comment-only slices preserved executable AST and non-comment tokens, passed independent review and the aggregate required CI gate. No ADR text changed.