Swift Comments That Matter
Compatibility note: this SKILL.md is the portable skill entrypoint for runtimes that load skill packages directly, including Cursor-compatible installs.
Canonical standard lives at standards/swift-comments-that-matter/STANDARD.md.
Purpose
Use this skill to produce comments that help future maintainers make safe changes.
Default rule:
- If text explains what the code does, improve the code.
- If text explains why code exists or what must not break, write the comment.
When To Use This Skill
Apply this skill when:
- reviewing
/// comments in Swift code
- refactoring low-signal comments
- documenting API contracts and invariants
- clarifying hidden behavior, side effects, or concurrency risks
Start Here
- Apply the decision flow in this file.
- Use the rewrite pattern: no comment -> bad -> good -> best.
- Follow writing guardrails and voice calibration.
Read When Needed
- Tone and context: docs/context.md
- Decision details: docs/decision-rules.md
- Quality checks: docs/checklist.md
- Example constraints: docs/example-constraints.md
- DocC boundaries: docs/docc-guidance.md
- Golden references: docs/golden-examples.md
- Review red flags: docs/review-red-flags.md
Quick Routing
- Quick review path:
docs/checklist.md
- Rewrite path:
docs/decision-rules.md + docs/golden-examples.md
- Review anti-pattern path:
docs/review-red-flags.md
- DocC boundary path:
docs/docc-guidance.md
Core Principle
If the text explains what the code does -> improve the code.
If the text explains why it exists or what must not break -> write the comment.
Contract Hierarchy
Prefer stronger sources of truth before prose:
- encode the contract in types, isolation, ownership, availability, diagnostics, or API shape;
- verify the contract with tests or preconditions when it is executable;
- comment only the decision, boundary, trade-off, or failure mode still invisible;
- move broader system context to DocC when it no longer belongs to one symbol.
Refactor-First Rule
Before writing a comment, first consider:
- renaming variables/functions/types
- extracting smaller functions
- simplifying control flow
If readability can be improved, refactor first.
Decision Flow
Before writing a comment, ask:
- Can naming or structure remove the need for the comment?
- Can types, actor isolation, ownership, availability, diagnostics, tests, or preconditions express the contract?
- Is there hidden framework behavior not obvious from code?
- Does correctness depend on identity, ordering, lifetime, cancellation, isolation, ownership, or backpressure?
- Is there a generated artifact or external source of truth?
- Does the comment include a verifiable condition for remaining true or being removed?
- Could another developer misuse this API or flow without compiler/test feedback?
If all answers are "no", do not comment.
Preferred Comment Sections
Use only when needed:
Important:
Why:
Assumption:
Constraint:
Invariant:
Risk:
Side Effects:
Concurrency:
Cancellation:
Isolation:
Ownership:
Lifetime:
Observation:
Backpressure:
Performance:
Compatibility:
Generated:
Prefer the most precise section. Use Concurrency: only for broad concurrency context; use Cancellation:, Isolation:, Ownership:, or Backpressure: when one of those is the actual risk.
When Not To Comment
Do not comment when:
- the sentence only repeats implementation
- the name can carry the meaning after small refactor
- the statement is generic and risk-free
- the comment adds length but no new decision context
Example Pattern Rule
Each scenario must include:
- No comment version (clean but incomplete)
- Bad comment version (common anti-pattern)
- Good comment version (useful)
- Best version (intent + constraints + reasoning)
Required Scenarios
The skill must cover:
- token refresh with concurrency issues
- download manager deduplication invariant
- cache eviction assumptions
- payment logic business constraints
- pricing and currency rounding constraints
- SwiftUI async lifecycle edge cases
- SwiftUI identity, lazy-container state lifetime, and repeatable
onAppear
- Observation dependencies that are registered implicitly by framework reads
- cancellation boundaries, cleanup, rollback, and point-of-no-return behavior
- actor isolation, task ownership, and non-copyable ownership/lifetime constraints
- stream ordering, cancellation, and backpressure
- generated-code source-of-truth and regeneration boundaries
- local diagnostic exceptions with a removal condition
- performance constraints backed by reproducible evidence
- compatibility workarounds with explicit removal conditions
- background task scheduling limitations
- analytics side effects
- public API contracts in frameworks
Anti-Patterns
Avoid:
- "This function does..."
- "This method is responsible for..."
- "This class..."
- line-by-line narration
- tutorial-style toy examples
- long comments with no constraints or risk
- TODOs without owner, condition, or exit criteria
- "temporary" or workaround comments without version, issue, or removal event
- performance claims without metric, fixture, trace, or benchmark
- comments that contradict types, compiler diagnostics, or tests
Writing Guardrails
When generating comments:
- NEVER start with:
- "This function..."
- "This method..."
- "This class..."
- Prefer direct statements, constraints, risks, and reasoning.
- Keep comments concise. Remove filler words.
Voice Calibration
Write like an experienced iOS engineer speaking to another engineer:
- human and direct
- no buzzwords
- no marketing tone
- no over-polished generic phrasing
DocC Boundary Rule
Use inline /// comments for:
- contracts
- invariants
- assumptions
- side effects
- local compatibility or performance constraints
Use DocC articles for:
- architecture explanations
- system flows
- domain concepts
- cross-module behavior
- version-dependent behavior spanning multiple symbols
Generated code boundary:
- do not add manual documentation to generated artifacts;
- document the schema, specification, or stable wrapper that owns the contract;
- include the regeneration command or process when it is not discoverable.
Compatibility Note
Examples target modern Swift codebases using Swift 6.3+/Xcode 27 concepts, Swift Concurrency, SwiftUI lifecycle behavior, Observation, and generated-code workflows. The principle is retrocompatible with older Swift projects: encode or test what you can, then comment only what remains invisible.
Examples
- examples/bad-comments.swift
- examples/better-comments.swift
- examples/concurrency.swift
- examples/invariants.swift
- examples/api-contracts.swift
- examples/pricing-rounding.swift
- examples/modern-contracts.swift
Additional Resources
- docs/principles.md
- docs/context.md
- docs/decision-rules.md
- docs/checklist.md
- docs/example-constraints.md
- docs/golden-examples.md
- docs/docc-guidance.md
- docs/review-red-flags.md
1---2name: swift-comments-that-matter3description: Write high-value Swift comments that explain intent, invariants, constraints, side effects, Swift Concurrency risks, SwiftUI lifecycle behavior, generated-code boundaries, and contracts not fully expressed by types or tests. Use when reviewing or authoring comments in iOS/macOS/watchOS/tvOS/visionOS codebases, especially to replace low-signal "what it does" comments with concise "why, what must not break, and when this guidance can be removed" documentation.4metadata:5 source: https://skillmd.com/skills/rgmez/swift-comments-that-matter6---78# Swift Comments That Matter910Compatibility note: this `SKILL.md` is the portable skill entrypoint for runtimes that load skill packages directly, including Cursor-compatible installs.11Canonical standard lives at `standards/swift-comments-that-matter/STANDARD.md`.1213## Purpose1415Use this skill to produce comments that help future maintainers make safe changes.1617Default rule:18- If text explains what the code does, improve the code.19- If text explains why code exists or what must not break, write the comment.2021## When To Use This Skill2223Apply this skill when:24- reviewing `///` comments in Swift code25- refactoring low-signal comments26- documenting API contracts and invariants27- clarifying hidden behavior, side effects, or concurrency risks2829## Start Here30311. Apply the decision flow in this file.322. Use the rewrite pattern: no comment -> bad -> good -> best.333. Follow writing guardrails and voice calibration.3435## Read When Needed3637- Tone and context: [docs/context.md](docs/context.md)38- Decision details: [docs/decision-rules.md](docs/decision-rules.md)39- Quality checks: [docs/checklist.md](docs/checklist.md)40- Example constraints: [docs/example-constraints.md](docs/example-constraints.md)41- DocC boundaries: [docs/docc-guidance.md](docs/docc-guidance.md)42- Golden references: [docs/golden-examples.md](docs/golden-examples.md)43- Review red flags: [docs/review-red-flags.md](docs/review-red-flags.md)4445## Quick Routing4647- Quick review path: `docs/checklist.md`48- Rewrite path: `docs/decision-rules.md` + `docs/golden-examples.md`49- Review anti-pattern path: `docs/review-red-flags.md`50- DocC boundary path: `docs/docc-guidance.md`5152## Core Principle5354If the text explains what the code does -> improve the code.55If the text explains why it exists or what must not break -> write the comment.5657## Contract Hierarchy5859Prefer stronger sources of truth before prose:601. encode the contract in types, isolation, ownership, availability, diagnostics, or API shape;612. verify the contract with tests or preconditions when it is executable;623. comment only the decision, boundary, trade-off, or failure mode still invisible;634. move broader system context to DocC when it no longer belongs to one symbol.6465## Refactor-First Rule6667Before writing a comment, first consider:68- renaming variables/functions/types69- extracting smaller functions70- simplifying control flow7172If readability can be improved, refactor first.7374## Decision Flow7576Before writing a comment, ask:771. Can naming or structure remove the need for the comment?782. Can types, actor isolation, ownership, availability, diagnostics, tests, or preconditions express the contract?793. Is there hidden framework behavior not obvious from code?804. Does correctness depend on identity, ordering, lifetime, cancellation, isolation, ownership, or backpressure?815. Is there a generated artifact or external source of truth?826. Does the comment include a verifiable condition for remaining true or being removed?837. Could another developer misuse this API or flow without compiler/test feedback?8485If all answers are "no", do not comment.8687## Preferred Comment Sections8889Use only when needed:90- `Important:`91- `Why:`92- `Assumption:`93- `Constraint:`94- `Invariant:`95- `Risk:`96- `Side Effects:`97- `Concurrency:`98- `Cancellation:`99- `Isolation:`100- `Ownership:`101- `Lifetime:`102- `Observation:`103- `Backpressure:`104- `Performance:`105- `Compatibility:`106- `Generated:`107108Prefer the most precise section. Use `Concurrency:` only for broad concurrency context; use `Cancellation:`, `Isolation:`, `Ownership:`, or `Backpressure:` when one of those is the actual risk.109110## When Not To Comment111112Do not comment when:113- the sentence only repeats implementation114- the name can carry the meaning after small refactor115- the statement is generic and risk-free116- the comment adds length but no new decision context117118## Example Pattern Rule119120Each scenario must include:1211. No comment version (clean but incomplete)1222. Bad comment version (common anti-pattern)1233. Good comment version (useful)1244. Best version (intent + constraints + reasoning)125126## Required Scenarios127128The skill must cover:129- token refresh with concurrency issues130- download manager deduplication invariant131- cache eviction assumptions132- payment logic business constraints133- pricing and currency rounding constraints134- SwiftUI async lifecycle edge cases135- SwiftUI identity, lazy-container state lifetime, and repeatable `onAppear`136- Observation dependencies that are registered implicitly by framework reads137- cancellation boundaries, cleanup, rollback, and point-of-no-return behavior138- actor isolation, task ownership, and non-copyable ownership/lifetime constraints139- stream ordering, cancellation, and backpressure140- generated-code source-of-truth and regeneration boundaries141- local diagnostic exceptions with a removal condition142- performance constraints backed by reproducible evidence143- compatibility workarounds with explicit removal conditions144- background task scheduling limitations145- analytics side effects146- public API contracts in frameworks147148## Anti-Patterns149150Avoid:151- "This function does..."152- "This method is responsible for..."153- "This class..."154- line-by-line narration155- tutorial-style toy examples156- long comments with no constraints or risk157- TODOs without owner, condition, or exit criteria158- "temporary" or workaround comments without version, issue, or removal event159- performance claims without metric, fixture, trace, or benchmark160- comments that contradict types, compiler diagnostics, or tests161162## Writing Guardrails163164When generating comments:165- NEVER start with:166 - "This function..."167 - "This method..."168 - "This class..."169- Prefer direct statements, constraints, risks, and reasoning.170- Keep comments concise. Remove filler words.171172## Voice Calibration173174Write like an experienced iOS engineer speaking to another engineer:175- human and direct176- no buzzwords177- no marketing tone178- no over-polished generic phrasing179180## DocC Boundary Rule181182Use inline `///` comments for:183- contracts184- invariants185- assumptions186- side effects187- local compatibility or performance constraints188189Use DocC articles for:190- architecture explanations191- system flows192- domain concepts193- cross-module behavior194- version-dependent behavior spanning multiple symbols195196Generated code boundary:197- do not add manual documentation to generated artifacts;198- document the schema, specification, or stable wrapper that owns the contract;199- include the regeneration command or process when it is not discoverable.200201## Compatibility Note202203Examples target modern Swift codebases using Swift 6.3+/Xcode 27 concepts, Swift Concurrency, SwiftUI lifecycle behavior, Observation, and generated-code workflows. The principle is retrocompatible with older Swift projects: encode or test what you can, then comment only what remains invisible.204205## Examples206207- [examples/bad-comments.swift](examples/bad-comments.swift)208- [examples/better-comments.swift](examples/better-comments.swift)209- [examples/concurrency.swift](examples/concurrency.swift)210- [examples/invariants.swift](examples/invariants.swift)211- [examples/api-contracts.swift](examples/api-contracts.swift)212- [examples/pricing-rounding.swift](examples/pricing-rounding.swift)213- [examples/modern-contracts.swift](examples/modern-contracts.swift)214215## Additional Resources216217- [docs/principles.md](docs/principles.md)218- [docs/context.md](docs/context.md)219- [docs/decision-rules.md](docs/decision-rules.md)220- [docs/checklist.md](docs/checklist.md)221- [docs/example-constraints.md](docs/example-constraints.md)222- [docs/golden-examples.md](docs/golden-examples.md)223- [docs/docc-guidance.md](docs/docc-guidance.md)224- [docs/review-red-flags.md](docs/review-red-flags.md)