refactor: enforce minimal, why-only comments — codify the rule, then apply it everywhere - #42
Merged
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This branch rewrites the commenting rule in the
writing-codeskill and then applies the new standard across every source and test file. The result is 68 files slimmed by 914 net lines: no restatements of code, no AC markers, no doc comments that parrot the signature.Why
The codebase carried a large volume of comments whose value was zero or negative — they repeated what the code said, cited acceptance criteria from specs that are already the authority, or justified the line's existence. These increase maintenance burden (changing code means changing the comment) and train the reader to ignore all comments. The fix is to set a higher bar in the skill and then delete everything that doesn't meet it.
What changed
writing-codeskill — Rule 7 rewritten. The default is no comment. A comment may exist only to explain a non-obvious why. All AC markers are banned. Doc comments must use///when they exist (per SwiftFormat), but most declarations still need none.ProviderProtocol,ProviderOrder,ProviderRegistry,ProviderOverrides,Keychain,BalanceThresholds,QuotaFormatting, and the JSON/Keychain helpers.QuotaViewModel,QuotaView,QuotaStatusResolver,MenuBarStatusIcon,RefreshIcon,SettingsWindowActivation, and visual-style files.Notes for review
writing-codeskill diff is worth reading closely — it's the policy that justifies every deletion.