mohitmujawdiya/swift-macos-quality

Swift macOS Code Quality Standards

Apply these standards to all Swift code in this project.

Architecture Rules

1. No @unchecked Sendable without thread-safe internals. If a class is @unchecked Sendable, it MUST protect all mutable state with NSLock, os_unfair_lock, or an actor. Document which lock protects which state.

2. Prefer final class everywhere. Only omit final when subclassing is intentionally designed for. This project has no inheritance — everything is final.

3. No force-unwraps (!) except for IBOutlet-style patterns. Use guard let or optional chaining. Implicitly unwrapped optionals (Type!) are only acceptable for properties set during a guaranteed lifecycle phase (e.g., applicationDidFinishLaunching).

4. No mixed concurrency models. Never use DispatchQueue.main.async inside a @MainActor context — you're already on the main actor. Use Task { @MainActor in } from non-MainActor contexts to dispatch to main.

5. Callbacks from background threads to @MainActor objects must use Task { @MainActor in }. Never DispatchQueue.main.async to call into @MainActor-isolated code.

Resource Management

6. Delegate/output objects must be strongly retained. Apple frameworks often weakly reference delegates. If you create a delegate object, store it in a property. (Example: SCStream does not retain SCStreamOutput — the AudioStreamDelegate must be stored.)

7. Clean up on teardown. Remove notification observers, invalidate URLSessions, remove audio taps, unregister hotkeys. Use applicationWillTerminate or deinit.

8. Guard against duplicate setup. If show() or start() can be called multiple times, guard against creating duplicate windows/streams/connections. Check state before creating new resources.

Naming & Style

9. Use enum for namespaces (types with only static members). Never use struct for stateless utility types — enum with no cases prevents accidental instantiation.

10. Prefer String(text.dropFirst(n)) over text.replacingOccurrences(of:) for prefix stripping. It's O(1) vs O(n) and communicates intent better.

11. Use Unicode escapes for special characters in code (\u{2325} for ⌥) rather than literal emoji/symbols, to avoid encoding issues across editors.

12. MARK comments for logical sections. Keep them consistent: // MARK: - Section Name.

Error Handling

13. Custom error types with LocalizedError conformance. Every module should have its own error enum. Always provide errorDescription.

14. No silent try? for operations that can meaningfully fail. Log the error at minimum. try? is only acceptable for truly optional operations (e.g., creating a directory that may already exist).

Performance

15. Audio processing callbacks are hot paths. Minimize allocations — no dictionary creation per frame, no string interpolation, no closure captures that cause retain/release churn. Pre-allocate buffers where possible.

16. calculateAudioLevel should be a static method — it needs no instance state and being static makes this clear.