Skip to content

refactor: enforce minimal, why-only comments — codify the rule, then apply it everywhere - #42

Merged
victorhqc merged 1 commit into
mainfrom
fix/trim-comments
Jul 25, 2026
Merged

refactor: enforce minimal, why-only comments — codify the rule, then apply it everywhere#42
victorhqc merged 1 commit into
mainfrom
fix/trim-comments

Conversation

@victorhqc

Copy link
Copy Markdown
Owner

Summary

This branch rewrites the commenting rule in the writing-code skill 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-code skill — 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.
  • Core — Stripped doc/line comments from ProviderProtocol, ProviderOrder, ProviderRegistry, ProviderOverrides, Keychain, BalanceThresholds, QuotaFormatting, and the JSON/Keychain helpers.
  • App — Stripped comments from QuotaViewModel, QuotaView, QuotaStatusResolver, MenuBarStatusIcon, RefreshIcon, SettingsWindowActivation, and visual-style files.
  • ClaudeCode provider — The largest cleanup: removed AC-citing comments and restatements from the refresher, locator, installer, cache store, statusline helper, and provider entry point.
  • Cursor, DeepSeek, ZAI providers — Removed restating and AC-cited comments from auth, locators, credential vault, token store, and provider entry points.
  • OpenAICodex provider — Light cleanup (locator, server client).
  • Tests — Comments removed from ~20 test files across all providers and Core. Test structure and assertions unchanged.

Notes for review

  • This is a pure comment deletion. No logic, no test assertions, no behavior changed. If a line of production code is missing, that's a bug — not part of this branch.
  • The writing-code skill diff is worth reading closely — it's the policy that justifies every deletion.
  • After merge, any new comment in a PR should be measured against the new rule 7.

@victorhqc
victorhqc merged commit 953d16b into main Jul 25, 2026
1 check passed
@victorhqc
victorhqc deleted the fix/trim-comments branch July 25, 2026 23:09
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