SOLID Principles

InvoiceService puts tax rules, SQL storage, and PDF layout in one type. A tax change, schema migration, or layout request would all require editing that same service.

struct InvoicePricing {
  func total(for invoice: Invoice) -> Decimal { /* tax rules */ }
}
struct InvoiceStore {
  func save(_ invoice: Invoice) throws { /* SQL schema */ }
}
struct InvoiceRenderer {
  func render(_ invoice: Invoice) -> Data { /* PDF layout */ }
}

final class InvoiceService {
  func total(_ invoice: Invoice) -> Decimal { /* tax rules */ }
  func save(_ invoice: Invoice) throws { /* SQL schema */ }
  func render(_ invoice: Invoice) -> Data { /* PDF layout */ }
}

Ask who requests each change, not how many methods a type has.

A cart total must apply the discount to the subtotal in the right order. Separate CartSubtotal, CartDiscount, and CartTotal types leave that sequence to every caller.

struct CartPricing {
  func total(for lines: [Line]) -> Decimal {
    let subtotal = subtotal(for: lines)
    return subtotal - discount(for: lines)
  }
  private func subtotal(for lines: [Line]) -> Decimal { /* … */ }
  private func discount(for lines: [Line]) -> Decimal { /* … */ }
}

struct CartSubtotal { func calculate(_ lines: [Line]) -> Decimal }
struct CartDiscount { func calculate(_ lines: [Line]) -> Decimal }
struct CartTotal { func calculate(_ lines: [Line]) -> Decimal }
// Each caller must combine these in the right order.

A responsibility can include several steps that serve one policy.

Subscription.renewalMessage embeds renewal wording in the domain type. Changing that text would require a domain edit even when expiration rules stay the same.

struct Subscription {
  var needsRenewal: Bool { isExpired }
}
struct RenewalMessage {
  func text(for subscription: Subscription) -> String {
    subscription.needsRenewal ? "Renew now in Settings" : "Active"
  }
}

struct Subscription {
  func renewalMessage() -> String {
    isExpired ? "Renew now in Settings" : "Active"
  }
}

Separate responsibilities when different policies drive their changes.

The discount function checks a kind for student and member promotions. Each new promotion adds another branch to the same function.

protocol DiscountPolicy {
  func discount(for order: Order) -> Decimal
}
struct StudentDiscount: DiscountPolicy {
  func discount(for order: Order) -> Decimal {
    order.total * 0.1
  }
}
func total(_ order: Order, using policy: DiscountPolicy) -> Decimal {
  order.total - policy.discount(for: order)
}

func discount(for order: Order, kind: String) -> Decimal {
  if kind == "student" { return order.total * 0.1 }
  if kind == "member" { return order.total * 0.2 }
  return 0 // Edit here for every new promotion.
}

Introduce an extension point when the variation actually recurs.

Idle, Busy, and other loading states are a fixed set for this screen. One type per state hides the full set and makes its labels harder to review together.

enum LoadingState {
  case idle, busy, failed
  var label: String {
    switch self {
    case .idle: "Ready"
    case .busy: "Loading"
    case .failed: "Try again"
    }
  }
}

protocol LoadingState { func label() -> String }
struct Idle: LoadingState { func label() -> String { "Ready" } }
struct Busy: LoadingState { func label() -> String { "Loading" } }
// Three more tiny types for fixed screen states.

Closed alternatives are a useful design choice, too.

Checkout, returns, and admin repeat the postal versus express choice. A new carrier would require changing each copy of that branch.

protocol ShippingQuoting {
  func quote(_ package: Package) async throws -> Quote
}
struct Checkout {
  let shipping: ShippingQuoting
  func quote(_ package: Package) async throws -> Quote {
    try await shipping.quote(package)
  }
}

if carrier == .postal { postal.quote(package) }
else if carrier == .express { express.quote(package) }
// Repeated in checkout, returns, and admin.

Look for repeated variation before introducing polymorphism.

MetadataOnlyDocument has a read method that always reports unsupported. A caller cannot rely on the capability that method advertises.

protocol DocumentMetadata {
  var title: String { get }
}
protocol ReadableDocument: DocumentMetadata {
  func read() throws -> Data
}
struct MetadataOnlyDocument: DocumentMetadata {
  let title: String
}

protocol ReadableDocument {
  func read() throws -> Data
}
struct MetadataOnlyDocument: ReadableDocument {
  func read() throws -> Data { throw DocumentError.unsupported }
}

Model the real capabilities instead of faking conformance.

ImageResizing does not state a 1024-pixel limit, but RemoteResizer rejects wider requests. A caller using a valid-looking size gets a provider-specific failure.

protocol ThumbnailResizing {
  // Contract: width and height are at most 1024 pixels.
  func thumbnailMax1024(_ image: Image, to size: Size) throws -> Image
}
struct RemoteThumbnailer: ThumbnailResizing {
  func thumbnailMax1024(_ image: Image, to size: Size) throws -> Image { /* … */ }
}

protocol ImageResizing {
  func resize(_ image: Image, to size: Size) throws -> Image
}
struct RemoteResizer: ImageResizing {
  func resize(_ image: Image, to size: Size) throws -> Image {
    guard size.width <= 1024 else { throw ResizeError.unsupported }
    /* … */
  }
}

State constraints in the shared contract, not in one surprise implementation.

A loader can have the right method signature and still return an old profile after an update. Reading once to warm a cache, renaming the profile, and reading again makes that broken promise visible.

protocol ProfileLoading {
  /// A read reflects the latest committed update.
  func load(_ id: UUID) async throws -> Profile
}
func checkFreshRead(_ loader: ProfileLoading, store: ProfileStore, id: UUID) async throws {
  _ = try await loader.load(id) // Warm any cache.
  try await store.rename(id, to: "Ada")
  let updated = try await loader.load(id)
  assert(updated.name == "Ada")
}

final class CachedProfileLoader: ProfileLoading {
  let store: ProfileStore
  var cache: [UUID: Profile] = [:]
  func load(_ id: UUID) async throws -> Profile {
    if let saved = cache[id] { return saved } // Old name after rename.
    let profile = try await store.load(id)
    cache[id] = profile
    return profile
  }
}

Write contract tests for the promises clients rely on.

InvoicePreview only loads invoices, but InvoiceRepository also requires saving and removal. A read-only preview adapter must implement operations it cannot use.

protocol InvoiceReading {
  func load(_ id: UUID) throws -> Invoice
}
protocol InvoiceWriting {
  func save(_ invoice: Invoice) throws
}
struct InvoicePreview {
  let invoices: InvoiceReading
}

protocol InvoiceRepository {
  func load(_ id: UUID) throws -> Invoice
  func save(_ invoice: Invoice) throws
  func delete(_ id: UUID) throws
}
// A read-only preview must implement all three.

Shape roles around clients, not around one large provider.

InvoiceEditor needs load and save, but AllInvoiceOperations also requires CSV export and archive purging. Those extra methods expand its dependency for no editor behavior.

typealias InvoiceEditing = InvoiceReading & InvoiceWriting
struct InvoiceEditor {
  let invoices: any InvoiceEditing
}
// Export and archive capabilities remain separate.

protocol AllInvoiceOperations {
  func load(_ id: UUID) throws -> Invoice
  func save(_ invoice: Invoice) throws
  func exportCSV() throws -> Data
  func purgeArchive() throws
}

Compose a larger role at the client that truly needs it.

BatchJob can run but cannot pause. Giving it a pause method makes an unsupported call look available until it throws or aborts.

protocol Runnable { func run() }
protocol Pausable { func pause() }
struct BatchJob: Runnable {
  func run() { /* … */ }
}
struct InteractiveJob: Runnable, Pausable {
  func run() { /* … */ }
  func pause() { /* … */ }
}

protocol Worker {
  func run()
  func pause()
}
struct BatchJob: Worker {
  func run() { /* … */ }
  func pause() { fatalError("Cannot pause") }
}

If an implementation cannot honor a method, revisit the role.

Checkout owns a LivePaymentGateway directly. Tests and alternate payment flows cannot supply another charger without changing Checkout.

protocol PaymentCharging {
  func charge(_ amount: Decimal) async throws
}
struct Checkout {
  let payments: PaymentCharging
  func pay(_ order: Order) async throws {
    try await payments.charge(order.total)
  }
}

struct Checkout {
  func pay(_ order: Order) async throws {
    let gateway = LivePaymentGateway()
    try await gateway.charge(order.total)
  }
}

Build concrete collaborators in the composition root.

The cloud SDK wrapper still exposes a JSON post and a path, so Checkout must know the vendor charge endpoint and payload format.

protocol PaymentCharging {
  func charge(_ amount: Decimal) async throws -> Receipt
}
struct VendorPaymentCharger: PaymentCharging {
  func charge(_ amount: Decimal) async throws -> Receipt {
    // Translate amount and receipt at the boundary.
  }
}

protocol CloudSDKWrapper {
  func postJSON(_ body: Data, path: String) async throws
}
// Checkout still knows "/v2/charges" and JSON fields.

Let the high-level use case define the abstraction.

ExpiryPolicy only needs the current date. A ClockFactoryProvider that creates another factory adds layers to obtain one value.

struct ExpiryPolicy {
  let now: () -> Date
  func isExpired(_ expiry: Date) -> Bool {
    expiry <= now()
  }
}
let policy = ExpiryPolicy(now: Date.init)

protocol ClockFactoryProvider {
  func makeClockFactory() -> ClockFactory
}
// Several layers exist only to read the current date.

Use the smallest boundary that expresses the dependency.