The repository has accumulated comments that cost a reader more than they give: essay-length doc blocks, @param blocks restating a Kotlin signature, section labels and ASCII dividers, and a lot of prose phrased as "this was X, now it is Y" — archaeology that git already holds.
This epic cuts them down, one slice per PR, and writes the rule down so the next branch does not re-grow them.
The rule
A comment earns its place by saying what the code cannot: a constraint, a trap with a cost, or a non-obvious reason. Class and method docs are a summary line plus at most one paragraph.
Cut: history, restatement, section labels, ASCII dividers, and @param/@return that repeat the signature.
Kept: constraints, traps, cross-file "change one, change the other" pairs, TODOs that name open work, and anything the toolchain reads.
Note that "no longer" is usually not history — "an answer it is no longer waiting on" is runtime state.
Slices
libs/ needs nothing: only two hand-written Kotlin files exist there, and both their comments are real gotchas.
Shape
Every diff is comment-only. The one exception across all five slices is three enum declarations split across lines so each constant can hold its own doc.
Found on the way, not fixed here
Each is a code change rather than a comment change, so each is left for its own decision:
DuplicateBlogTitleException has zero references outside its own file. Its own comment admitted it. The doc now says so plainly; deleting the class is a separate call.ContactAdapter and ContactListAdapter carried the same pasted header, both claiming to be a single merged contract. They are two interfaces split by concern, and the doc described a merge that had been undone.- Three stranded doc blocks in the api service layer —
RecoveryTokenValidator, TeamRosterService, CommitteeMemberService — where inserting a method directly beneath an existing doc had silently re-pointed it, leaving the documented method undocumented. All three are fixed, but three occurrences of one pattern suggests it recurs.
The repository has accumulated comments that cost a reader more than they give: essay-length doc blocks,
@paramblocks restating a Kotlin signature, section labels and ASCII dividers, and a lot of prose phrased as "this was X, now it is Y" — archaeology that git already holds.This epic cuts them down, one slice per PR, and writes the rule down so the next branch does not re-grow them.
The rule
A comment earns its place by saying what the code cannot: a constraint, a trap with a cost, or a non-obvious reason. Class and method docs are a summary line plus at most one paragraph.
Cut: history, restatement, section labels, ASCII dividers, and
@param/@returnthat repeat the signature.Kept: constraints, traps, cross-file "change one, change the other" pairs,
TODOs that name open work, and anything the toolchain reads.Note that "no longer" is usually not history — "an answer it is no longer waiting on" is runtime state.
Slices
docs/agents/comments.mdservices/api/src/mainservices/api/src/{test,integrationTest}services/frontend/srctests/systemlibs/needs nothing: only two hand-written Kotlin files exist there, and both their comments are real gotchas.Shape
Every diff is comment-only. The one exception across all five slices is three enum declarations split across lines so each constant can hold its own doc.
Found on the way, not fixed here
Each is a code change rather than a comment change, so each is left for its own decision:
DuplicateBlogTitleExceptionhas zero references outside its own file. Its own comment admitted it. The doc now says so plainly; deleting the class is a separate call.ContactAdapterandContactListAdaptercarried the same pasted header, both claiming to be a single merged contract. They are two interfaces split by concern, and the doc described a merge that had been undone.RecoveryTokenValidator,TeamRosterService,CommitteeMemberService— where inserting a method directly beneath an existing doc had silently re-pointed it, leaving the documented method undocumented. All three are fixed, but three occurrences of one pattern suggests it recurs.