Skip to content

[Trebuchet] refactor: Tighten code comments for concision (~2520 comment lines) #2691

Description

@LordOfMyatar

Current State

Follow-up to #2672, which swept the shared libraries only. Code comments in this tool have
not been reviewed for concision. Wordy comments cost tokens on every session that reads the
file, repeatedly, for the life of the file.

Proposed Change

Sweep this tool's comments using the rules established in #2672:

Delete:

  • XML <summary> that restates the identifier — /// <summary>Tag of this creature</summary> on Tag
  • <param> tags that restate the parameter name without adding a constraint or unit
  • Step narration above self-evident code

Keep:

  • Anything the code cannot express: units, ranges, capacity math, performance rationale, gotchas
  • Format and 2DA provenance, BioWare spec and neverwinter.nim references
  • Issue references, dated one-liner logs, // TODO (#N): markers

Collapse rather than delete when the doc carries real information: a three-line XML block
whose summary is one clause becomes one line.

Constraints

  • Comment-only diffs. No behavior changes in the same commit.
  • When unsure whether a comment carries information, keep it. A needless comment wastes
    tokens; a deleted insight costs a re-derivation.
  • Verify the tool builds with no new warnings and its tests pass before committing.

Note on approach

Parallel agents sweeping a shared working tree clobbered each other during #2672. Run this
tool's sweep as a single agent, or give each agent an isolated worktree.


🤖 Generated with Claude Code

Activity

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

    TrebuchetTrebuchet - Radoub Launcher and Module Managertech-debtTechnical debt and code quality improvements

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions