Skip to content

Say the rule, not the process, in code comments - #224

Open
Pixnop wants to merge 1 commit into
devfrom
chore/scrub-tooling-comments
Open

Say the rule, not the process, in code comments#224
Pixnop wants to merge 1 commit into
devfrom
chore/scrub-tooling-comments

Conversation

@Pixnop

@Pixnop Pixnop commented Aug 22, 2026

Copy link
Copy Markdown
Contributor

A sweep over comments that explained a file's placement by referring to the process that produced it rather than to the rule that governs it. A reader a year from now has the code and nothing else, so a comment pointing at work in flight or at a checklist step is worse than no comment at all.

Four comments carried a shorthand marker for a deliberate limitation. They now say "Known limit" and read the same otherwise. Two referred to work happening elsewhere at the time, one of them to a file that may not have existed yet on that branch; both now describe the boundary itself. Six spoke of a stage and its exit gate, which is process vocabulary for a rule that stands on its own: nothing under src/renderer/src/components may touch the preload bridge, and no file under features/mods may mention window.api. That is what they say now. Two test comments dated themselves against a stage rather than against the behaviour they pin.

No code changed, only comments, so the unchanged suite passing is the whole proof.

@Pixnop
Pixnop requested a review from Zaldaryon August 22, 2026 22:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant