Sportstime/.planning/codebase/CONVENTIONS.md

Coding Conventions

Analysis Date: 2026-01-09

Naming Patterns

Files:

• PascalCase for all Swift files: TripDetailView.swift, DataProvider.swift
• Views: *View.swift (e.g., HomeView.swift, TripCreationView.swift)
• ViewModels: *ViewModel.swift (e.g., TripCreationViewModel.swift)
• Services: *Service.swift (e.g., LocationService.swift)
• Tests: *Tests.swift (e.g., TravelEstimatorTests.swift)

Functions:

• camelCase for all functions: loadInitialData(), planItineraries()
• No special prefix for async functions
• Handlers: handle* pattern not heavily used; actions named directly

Variables:

• camelCase: selectedSports, startDate, gamesOnThisDay
• No underscore prefix for private (Swift convention)
• Constants: camelCase (no UPPER_SNAKE_CASE)

Types:

• PascalCase for all types: Stadium, TripPreferences, PlanningRequest
• No I prefix for protocols: ScenarioPlanner (not IScenarioPlanner)
• Enums: PascalCase name, camelCase cases: Sport.mlb, FailureReason.noGamesFound

Code Style

Formatting:

• 4-space indentation (inferred from code)
• No SwiftLint or SwiftFormat configuration
• Follows standard Swift conventions organically

Section Organization:

• // MARK: - for major sections (560 occurrences across codebase)
• Pattern: // MARK: - Section Name
• Example sections: // MARK: - Properties, // MARK: - Public API, // MARK: - Private

File Headers:

//
//  FileName.swift
//  SportsTime
//
//  Optional description line.
//

Import Organization

Order:

1. Foundation/Swift standard library
2. Apple frameworks (SwiftUI, SwiftData, MapKit)
3. Project imports (@testable import SportsTime in tests)

Grouping:

• No blank lines between import groups
• Alphabetical not enforced

Path Aliases:

• None used (no module aliasing)

Error Handling

Patterns:

• Explicit result types: ItineraryResult enum with .success / .failure
• throws for recoverable service errors
• Async functions use async throws

Error Types:

• PlanningFailure with FailureReason enum and user message
• ConstraintViolation for planning constraint issues
• SwiftData errors propagated via try

Async:

• async/await throughout (no completion handlers)
• try await pattern for async throwing functions

Logging

Framework:

• print() with emoji prefixes for debugging
• No production logging framework (Sentry, etc.)

Patterns:

• Warning: print("⚠️ Warning message")
• Info: print("ℹ️ Info message")
• Error: print("❌ Error: \(error)")
• Debug only; no structured logging

Comments

When to Comment:

• Explain why, not what
• Document business logic and edge cases
• Complex algorithms get explanatory comments

Documentation Comments:

• Triple-slash /// for public APIs (487 occurrences)
• Example:

  /// Main entry point for trip planning.
  /// - Parameter request: The planning request containing all inputs
  /// - Returns: Ranked itineraries on success, or explicit failure
  func planItineraries(request: PlanningRequest) -> ItineraryResult
  

TODO Comments:

• Format: // TODO: description
• Currently only 1 TODO in codebase: RouteDescriptionGenerator.swift:30

Function Design

Size:

• No strict line limit enforced
• Large files exist (800+ lines in some services)
• Complex logic extracted to private helpers

Parameters:

• Default parameters used extensively
• Options objects for complex configuration: PlanningRequest, TripPreferences

Return Values:

• Explicit returns
• Result types for operations that can fail
• Optional for lookups that may not find data

Module Design

Exports:

• No barrel files (Swift doesn't use this pattern)
• Public API via public/internal access control

Access Control:

• private for implementation details
• internal (default) for module-internal
• public for Codable conformances and cross-module APIs

Property Wrappers:

• @Observable for ViewModels (modern pattern)
• @Model for SwiftData entities
• @MainActor for UI-bound services
• @Query for SwiftData queries in views

---

Convention analysis: 2026-01-09 Update when patterns change