145 lines
8.6 KiB
Markdown
145 lines
8.6 KiB
Markdown
# Swift coding rules (canonical)
|
|
|
|
The canonical, scrubbed Swift coding rules. This is the **Swift domain**: the
|
|
language- and platform-specific craft of writing Swift well. It sits on top of a
|
|
vendored **core spine** of cross-cutting engineering discipline (see
|
|
[`core/`](core/)).
|
|
|
|
Each file here is one Swift rule area. `CONVENTIONS.md` is the short overview; this
|
|
repository is the full set, with the cross-cutting discipline vendored under
|
|
[`core/`](core/). Examples use a sample tile-based static site generator named
|
|
Tiledown (the `TileKit` library plus the `tile-down` executable); replace the
|
|
example names with your project's when you adopt these.
|
|
|
|
## The core spine
|
|
|
|
The cross-cutting engineering discipline that governs *how* work is done and
|
|
reported, independent of language or domain, lives in [`core/`](core/). The Swift
|
|
rules here do not duplicate it; they build on it. Read the core spine first:
|
|
|
|
- `core/no-shortcuts-first-principles.md` - the core ethic: no shortcuts, derive
|
|
from first principles, hold to Knuth's standard of care.
|
|
- `core/proof-discipline.md` - framing a correctness claim as separately provable
|
|
layers, each with an explicit epistemic status.
|
|
- `core/round-trip-transformation.md` - any two-way transform (parse/print,
|
|
encode/decode) is one invertible description, proven by the round-trip law.
|
|
- `core/first-principles-analysis.md` - depth target for analysis, plus
|
|
measurement discipline (every number traceable to a command).
|
|
- `core/verification.md` - no "done" without fresh command output.
|
|
- `core/testing-discipline.md` - real tests on every change; a build is not a test.
|
|
- `core/systematic-debugging.md` - reproduce, isolate, explain, then fix.
|
|
- `core/brainstorming.md` and `core/writing-plans.md` - design and planning gates
|
|
before non-trivial work.
|
|
- `core/commits.md`, `core/git-discipline.md` - Conventional Commits; issues,
|
|
labels, branches, PRs, remotes.
|
|
- `core/file-naming.md`, `core/folder-grouping.md` - filename conventions and when
|
|
to flatten one-file folders.
|
|
- `core/rules.md`, `core/self-improve.md` - authoring rules for an agent, and when
|
|
a recurring correction should become one.
|
|
|
|
## Where an app starts
|
|
|
|
Before any UI framework is named, an app starts at its business rules and the
|
|
domain that enforces them.
|
|
|
|
- [business-rules-and-constraints.md](business-rules-and-constraints.md) -
|
|
MANDATORY, the first artifact: the business rules written as explicit checkable
|
|
statements, plus the constraints that bound them (which external REST services
|
|
and their contracts, what compliance, which auth model), defined up front.
|
|
- [domain-first.md](domain-first.md) - MANDATORY: an app starts at the domain and
|
|
business rules, framework-free and headless-provable; the UI framework is the
|
|
last, reversible, and plural choice, never the first decision.
|
|
|
|
## Language and platform craft (engine, today)
|
|
|
|
- [code-style.md](code-style.md) - namespacing discipline, file naming,
|
|
one-type-per-file.
|
|
- [namespacing.md](namespacing.md) - caseless `enum` vs `struct` vs `class` for
|
|
namespace anchors.
|
|
- [dependency-injection.md](dependency-injection.md) - no singletons, inject every
|
|
collaborator through `init`, protocol seams.
|
|
- [concurrency.md](concurrency.md) - Swift 6 strict concurrency: `Sendable`,
|
|
actors, `@MainActor`.
|
|
- [cross-platform.md](cross-platform.md) - the same sources build on Apple
|
|
platforms and Linux (and Windows where noted); guard platform-divergent code
|
|
behind a protocol seam.
|
|
- [linux-server.md](linux-server.md) - server-side operational rules for the
|
|
`serve` command and any networking.
|
|
- [testing.md](testing.md) - Swift Testing, `@Test` / `#expect`, test isolation.
|
|
- [formatting-and-linting.md](formatting-and-linting.md) - SwiftFormat and
|
|
SwiftLint, enforced by a pre-commit hook and again in CI.
|
|
- [documentation.md](documentation.md) - DocC catalogs and `///` requirements.
|
|
- [documentation-search.md](documentation-search.md) - verify API facts against an
|
|
authoritative documentation index, not from memory: query it with keywords and
|
|
read the results for Apple-API facts; it is a search engine, not an agent.
|
|
- [framework-policy.md](framework-policy.md) - stay inside Apple's own SDKs and the
|
|
Swift-native ecosystem; Linux falls back to C or C++ only.
|
|
|
|
## Packages
|
|
|
|
- [package-structure.md](package-structure.md) - workspace and package layout: one
|
|
`Package.swift` under `Packages/`, many targets, `Apps/` for app targets.
|
|
- [package-architecture.md](package-architecture.md) - single-responsibility
|
|
targets with unidirectional dependencies.
|
|
- [package-import-contract.md](package-import-contract.md) - per-target allowed
|
|
imports; applies now, the engine and CLI are already two targets.
|
|
- [shared-protocols.md](shared-protocols.md) - the cross-target protocol seam.
|
|
- [openapi-generated.md](openapi-generated.md) - rules for code generated from an
|
|
OpenAPI document and the hand-written code that surrounds it.
|
|
|
|
## ExtremePackaging
|
|
|
|
The granular packaging doctrine lives under [`exp/`](exp/): a monorepo split into
|
|
many single-responsibility SPM packages with explicit, unidirectional dependencies,
|
|
for isolated compilation, parallel builds, and per-package testability. The two
|
|
core files are loaded on every Swift session; the rest load on demand.
|
|
|
|
- [exp/critical-rules.md](exp/critical-rules.md) - core: the five rules that gate
|
|
every package decision (single responsibility, explicit deps, granularity,
|
|
naming, layer architecture).
|
|
- [exp/when-to-create.md](exp/when-to-create.md) - core: the decision tree and
|
|
DO/DON'T list for when a new package is warranted.
|
|
- [exp/implementation-patterns.md](exp/implementation-patterns.md) - patterns for
|
|
foundation, feature, middleware, API, component, and font packages, and for
|
|
aggregators.
|
|
- [exp/dependency-management.md](exp/dependency-management.md) - cross-package
|
|
dependencies, platform-conditional code, avoiding cycles.
|
|
- [exp/package-swift.md](exp/package-swift.md) - the closure-with-local-variables
|
|
pattern for the `deps`, `allProducts`, and `targets` arrays.
|
|
- [exp/common-mistakes.md](exp/common-mistakes.md) - anti-patterns paired with the
|
|
canonical fix, for code review of `Package.swift` changes.
|
|
- [exp/app-target.md](exp/app-target.md) - adding or modifying an app target
|
|
(SwiftUI, UIKit, AppKit entry points).
|
|
- [exp/testing.md](exp/testing.md) - the per-package test target and cross-package
|
|
test doubles (architecture angle; full rules in [testing.md](testing.md)).
|
|
- [exp/migration.md](exp/migration.md) - extracting code into a new package or
|
|
splitting a large one.
|
|
- [exp/build-performance.md](exp/build-performance.md) - the build-time rationale
|
|
behind the granularity.
|
|
- [exp/verification.md](exp/verification.md) - the final checklist before an
|
|
ExtremePackaging change is considered done.
|
|
|
|
## Parsing and validation
|
|
|
|
- [parsing-rules.md](parsing-rules.md) - parse first, validate second; the
|
|
OpenAPIKit parsing idiom over any structured input.
|
|
- [validation-rules.md](validation-rules.md) - composable `Validation<Subject>`
|
|
values, never imperative if-trees; every public type is validated or excluded
|
|
with a reason, enforced mechanically.
|
|
|
|
## UI
|
|
|
|
The UI rules live under [`ui/`](ui/). Any code with UI keeps the renderer thin over a framework-free model, and tests the flows from a shared scenario corpus.
|
|
|
|
- [ui/pre-ui-layer.md](ui/pre-ui-layer.md) - MANDATORY: all display state and behavior in a framework-free, value-typed model (Domain + Surface); one `perform(Intent)` write channel; renderers are the only UI import, gated mechanically.
|
|
- [ui/three-renderers.md](ui/three-renderers.md) - build the same UI in all three Apple SDKs (SwiftUI, UIKit, AppKit) over the one model: the architecture's payoff and a comparison instrument for which framework behaves best in a scenario.
|
|
- [ui/swiftui-views.md](ui/swiftui-views.md) - the SwiftUI renderer: view architecture and identity.
|
|
- [ui/uikit-views.md](ui/uikit-views.md) - the UIKit renderer: `UIViewController`/`UIView` adapters, diffable data sources, re-pull on the change signal.
|
|
- [ui/appkit-views.md](ui/appkit-views.md) - the AppKit renderer: `NSViewController`/`NSView` adapters, `withObservationTracking`, programmatic menus.
|
|
- [ui/view-models.md](ui/view-models.md) - view-model responsibilities and patterns.
|
|
- [ui/components.md](ui/components.md) - the component system.
|
|
- [ui/colors.md](ui/colors.md) - the color system.
|
|
- [ui/fonts.md](ui/fonts.md) - font registration in SPM packages.
|
|
- [ui/pom.md](ui/pom.md) - Page Object Model for UI tests: screens behind page objects, identifiers from one shared source.
|
|
- [ui/flowspec.md](ui/flowspec.md) - declarative UI scenarios driven by [FlowSpec](https://github.com/mihaelamj/FlowSpec): one flow, many renderers, replayed headless and on-device.
|