Skip to content

Code health: strip history/review-round citations from src comments #1934

Closed

Description

@pzfreo

Part of the code-health epic. Evidence pinned to main @ 71b8c94.

Problem

Comments in src record history rather than explaining the current code:

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 plain ADR n in src, and keep the "was" mapping only in docs/adr/. This needs a test_adr_corpus change, so it is the maintainer's call.
  • Optional: a ratchet test on the count of Codex #… and r[0-9] citations in src.

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 #number mentions 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).

Activity

  1. added
    documentationImprovements or additions to documentation
    tech-debtInternal maintainability or refactoring work
    on Sep 28, 2026
  2. pzfreo commented on Sep 28, 2026

    @pzfreo
    OwnerAuthor

    First module slice merged in #1970 (1ab06071). annotations/from_model.py Python-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.

  3. pzfreo commented on Sep 29, 2026

    @pzfreo
    OwnerAuthor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationtech-debtInternal maintainability or refactoring work

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions