references/file-api-discipline.md
309 tokens · o200k_base · 1,398 bytes
Source excerpt starting at line 1.# File and API Discipline Expands the file organization, DocC, and design-smell rules in [../SKILL.md](../SKILL.md). ## What gets its own file Public API types, internal types with meaningful bodies, private nested types that grew past a tiny helper, type-erased wrappers, and conformance extensions for externally owned types. A helper can stay with its parent while it is private and trivial (a nested enum for local branching, a one-line private extension). Move it the moment it has lifecycle, state, a protocol conformance, or enough logic to test independently. ## DocC quick examples ```swift/// Stores a typed ``CmuxSetting`` value.``` ```swift/// Reads from `UserDefaults.standard` only when injected by the caller.``` Double backticks reference symbols; plain backticks are non-symbol code. ## Design smells ```swift// Fake namespace: no instances, no DI, no test seam.enum Foo { static func bar() { ... }}``` Runtime-state singletons (`static let shared` / `standard` / `default`) are constructed at app startup and injected instead. `static let` stays legal for identifiers, schema entries, and enum cases. A `guard` plus `assertionFailure` plus a fallback usually means the type model is too weak. Encode the invariant in the type system. A hand-maintained list that mirrors declared items drifts silently. Derive it via reflection or a macro where practical.