Skip to content

chore: brutal comment audit — obliterate restatement, narration, decoration - #675

Merged
3lvis merged 1 commit into
masterfrom
chore/comment-audit-obliterate
Jun 27, 2026
Merged

chore: brutal comment audit — obliterate restatement, narration, decoration#675
3lvis merged 1 commit into
masterfrom
chore/comment-audit-obliterate

Conversation

@3lvis

@3lvis 3lvis commented Jun 27, 2026

Copy link
Copy Markdown
Owner

Ran the comment-audit bar at full aggression across the whole first-party tree — doc comments included — and stripped everything the code already says.

Net: −336 comment lines (479 deleted / 143 kept-or-reflowed, 47 files).

What died

  • Signature-restating docstrings (///), public or not — @SyncQuery/@SyncModel/publisher-family navigation docs, init/getter docs that re-say the name.
  • Narration & step labels// insert, // Reconnect:, // Act/// given-when-then, assertion restatement (the test names + messages carry it).
  • Decoration — every // MARK: (22 of them).
  • Snapshot rot & duplicated rationale — counts, "currently", and whys repeated at call sites.

What survived (the narrow bar)

Only what the code genuinely can't express, trimmed to the load-bearing clause:

  • external / wire-protocol facts (server LWW, upsert-by-id, payload absent vs null semantics);
  • non-obvious whys (token-advances-only-on-clean-pass, capture-before-upload, per-pass inbox annotation);
  • framework gotchas (SwiftData history .preserveValueOnDeletion, @unchecked Sendable soundness, nil != "inbound" is SQL NULL);
  • justifications for suspicious code (force-casts, empty closures, force-unwraps that are intentional);
  • the repo-required UI-test "why this costly test earns its place" rationales.

Verification

Behavior-neutral (comment-only + reflow). SwiftSync 190, DemoCore 44, DemoBackend 32, demo app builds, DemoUITests 3/3 — all green.

…ration

Apply the comment-audit bar across the whole first-party tree, doc comments
included. Cut signature-restating docstrings (public or not), step-label
narration, snapshot rot, duplicated rationale, and all // MARK: decoration.
Keep only what the code can't say: external/wire-protocol facts, non-obvious
whys (LWW/upsert/token semantics), framework gotchas (SwiftData history,
@unchecked Sendable soundness, SQL-null predicates), and justifications for
suspicious-looking code.

Behavior-neutral: comment-only. SwiftSync 190, DemoCore 44, DemoBackend 32,
demo build + DemoUITests 3/3 all green.
@3lvis
3lvis marked this pull request as ready for review June 27, 2026 09:16
@3lvis
3lvis merged commit 6b00ff9 into master Jun 27, 2026
12 checks passed
@3lvis
3lvis deleted the chore/comment-audit-obliterate branch June 27, 2026 09:58
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