P0: Apply commenting style guide to App/AppDelegate.swift #65

New Issue

2026-05-12T19:20:53Z

KofTwentyTwo commented

2026-05-12 19:20:53 +00:00

(Migrated from github.com)

Goal

Bring App/AppDelegate.swift (~2700 LOC) up to the standard in .planning/code-commenting-guide.md. This is the install-chain cliff — the file every new developer reads first.

Constraints

ONE atomic commit. No code behavior changes — comments + docstrings only.
18/18 boundary gates green.
Apply the guide's 5 comment shapes:
- 5-line opener at the top of the file
- Type-level /// docstring on AppDelegate with Overview + Topics + Threading + See Also
- Method-level docstrings on public + key private methods
- ASCII diagram of the install order in the file header
- "Before you edit" invariants block (don't add a new HudState writer, don't reorder install tasks, share inProcessToolRegistry, AppleScript MUST have requiresConfirmation: true, etc.)
- MARK dividers as a table of contents

Anti-patterns to remove (cited examples)

Plan 10-02c (B-01b): ... style comments — rewrite with WHY-first prose, audit IDs as parenthetical footnotes.
Stale references to closed Plan IDs or removed types.
Bare TODO: without issue link.

Parent epic

#64

Source

.planning/code-commenting-guide.md → Migration plan → P0

## Goal Bring `App/AppDelegate.swift` (~2700 LOC) up to the standard in `.planning/code-commenting-guide.md`. This is the install-chain cliff — the file every new developer reads first. ## Constraints - ONE atomic commit. No code behavior changes — comments + docstrings only. - 18/18 boundary gates green. - Apply the guide's 5 comment shapes: - 5-line opener at the top of the file - Type-level `///` docstring on `AppDelegate` with Overview + Topics + Threading + See Also - Method-level docstrings on public + key private methods - ASCII diagram of the install order in the file header - "Before you edit" invariants block (don't add a new HudState writer, don't reorder install tasks, share `inProcessToolRegistry`, AppleScript MUST have requiresConfirmation: true, etc.) - MARK dividers as a table of contents ## Anti-patterns to remove (cited examples) - `Plan 10-02c (B-01b): ...` style comments — rewrite with WHY-first prose, audit IDs as parenthetical footnotes. - Stale references to closed Plan IDs or removed types. - Bare `TODO:` without issue link. ## Parent epic #64 ## Source .planning/code-commenting-guide.md → Migration plan → P0

KofTwentyTwo commented

2026-05-12 20:08:56 +00:00

(Migrated from github.com)

Closed by commit 281b909. Applied the style guide to App/AppDelegate.swift.

Closed by commit 281b909. Applied the style guide to App/AppDelegate.swift.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: KofTwentyTwo/Jarvis#65