/coding-best-practices

name: coding-best-practices
description: Reviews Swift/iOS code for adherence to modern Swift idioms, Apple platform best practices, architecture patterns, and code quality standards. Use when user mentions best practices, code review, clean code, refactoring, or wants to improve code quality.
allowed-tools: [Read, Glob, Grep]
last_verified: 2026-07-16
review_by: 2027-06-22
os_version: iOS 27 / macOS 27

Coding Best Practices Skill

Reviews Swift/iOS code for adherence to modern Swift idioms, Apple platform best practices, architecture patterns, and code quality standards.

When This Skill Activates

Use this skill when the user:

• Asks for code review or code quality check
• Mentions "best practices", "clean code", or "refactoring"
• Wants to improve existing code
• Requests architecture or design pattern review
• Asks about Swift idioms or modern patterns
• Wants performance optimization suggestions

Review Process

1. Identify Scope

• If user specifies files/classes, review those
• Otherwise, ask which areas to focus on or review recent changes
• Prioritize ViewModels, business logic, and data layer over simple views

2. Load Reference Patterns

Before starting the review, familiarize yourself with the reference patterns by reading the following files in `.claude/skills/coding-best-practices/`:

• **swift-patterns.md** - Optionals, type safety, collections, error handling, naming
• **swiftui-patterns.md** - State management, view composition, performance
• **architecture-patterns.md** - MVVM, code organization, memory management, security
• **coredata-patterns.md** - Core Data best practices, fetching, saving, relationships

3. Review Categories

Apply these review categories based on the code type:

**For All Code:**

• Swift language idioms (optionals, type safety, collections)
• Naming conventions
• Error handling
• Memory management

**For SwiftUI Code:**

• State management (`@State`, `@Observable` + `@Bindable`; legacy `@StateObject` / `@ObservedObject` pre-iOS 17)
• View composition and performance
• MVVM separation

**For ViewModels:**

• Business logic placement
• MVVM architecture adherence
• Testability (dependency injection)

**For Core Data Code:**

• Context management
• Save/fetch patterns
• Relationship handling
• CloudKit integration

4. Review Output Format

Provide review in this structure:

✅ Strengths Found

• List well-implemented patterns
• Highlight good practices
• Acknowledge clean code sections

⚠️ Issues Found

For each issue, use this format:

**Category: [Category Name]**

**[Priority]: [File.swift:line]** - [Issue description]

// Current:
[problematic code]

// Suggested:
[improved code]

// Reason: [explanation]

**Priority Levels:**

• **High**: Will cause bugs, crashes, or serious issues
• **Medium**: Inefficient, hard to maintain, or non-idiomatic
• **Low**: Minor improvements, nice-to-haves

📊 Code Quality Score

**Overall: X/10**

• Swift Idioms: X/10
• Architecture: X/10
• Error Handling: X/10
• Naming: X/10
• Organization: X/10
• Performance: X/10

📋 Recommendations

1. **High Priority**: [Critical issues] 2. **Medium Priority**: [Improvements] 3. **Low Priority**: [Nice-to-haves]

🔧 Quick Wins

List 3-5 easy fixes that provide immediate value

Review Checklist

Use this comprehensive checklist during review:

Swift Language

• [ ] No force unwrapping unless intentional
• [ ] Proper optional handling (guard, if let, ??)
• [ ] Enums instead of string/int constants
• [ ] Functional collection operations (map, filter, etc.)
• [ ] Proper error handling (not silent try?)
• [ ] Clear, descriptive naming

SwiftUI

• [ ] Correct property wrapper usage
• [ ] No ViewModels created in body
• [ ] Views broken into components
• [ ] No heavy computation in body
• [ ] Single source of truth
• [ ] Reaches for the modern baseline APIs (see Modern SwiftUI Baseline below)

Architecture

• [ ] MVVM separation maintained
• [ ] Business logic in ViewModels
• [ ] UI logic in Views only
• [ ] Proper code organization with MARK
• [ ] Private by default

Core Data

• [ ] Using shared context
• [ ] hasChanges check before save
• [ ] Typed fetch requests
• [ ] Safe property access
• [ ] Proper error handling

Memory Management

• [ ] [weak self] in escaping closures
• [ ] Weak delegates
• [ ] No retain cycles

Testing & Security

• [ ] Testable code structure
• [ ] Dependency injection
• [ ] No hardcoded secrets
• [ ] Input validation
• [ ] Safe logging

Modern SwiftUI Baseline (What to Reach For Today)

The default APIs to expect in a healthy SwiftUI codebase. During review, flag code still on the legacy column — each line is: reach for this / when. Version floors in parentheses; anything unmarked is broadly available.

**Structure & navigation**

• `NavigationStack` / `NavigationSplitView` — `NavigationView` is deprecated; value-based links + `navigationDestination` (iOS 16+)

**State & data flow**

• `@Observable` over `ObservableObject` — per-property invalidation means fewer re-renders, no `@Published` (iOS 17+)
• `@State` lazily initializes `@Observable` classes (behavior backported to iOS 17) — delete double-initialization workarounds and "cheap placeholder default" hacks
• `@Previewable` inside `#Preview` — use `@State` directly in a preview without a wrapper view (Xcode 16+)

**Presentation & input**

• `presentationDetents` for resizable sheets — half-height/custom stops instead of full-screen covers (iOS 16+)
• Item-binding `alert(_:item:)` / `confirmationDialog(_:item:)` — prefer over `isPresented` + a side-car state variable; the item carries the context (WWDC26)
• `searchable` with scopes, tokens, and suggestions + `searchFocused` for programmatic search-field focus — structured search over hand-rolled filter bars
• `@FocusState` + `defaultFocus` + `focused(_:equals:)` for focus management; `onKeyPress` for hardware-keyboard handling
• Spring presets `.smooth` / `.snappy`