Clean Code

A reader should not have to trace assignments to discover what a value means.

let overdueInvoices = invoices.filter { $0.dueDate < today }

let list = invoices.filter { $0.dueDate < today }

Use the domain term the next reader would search for.

A misleading label creates a false mental model even when the implementation works.

let accountsByID: [UUID: Account] = [:]

let accountList: [UUID: Account] = [:]

Names are a contract with the reader.

Inconsistent synonyms make engineers wonder whether two operations differ.

func loadOrders() async throws -> [Order]
func loadInvoices() async throws -> [Invoice]

func fetchOrders() async throws -> [Order]
func retrieveInvoices() async throws -> [Invoice]

Keep differences in names meaningful.

A short name is only clear within the right scope.

struct Order {
  let customerEmail: String
}

struct Order {
  let orderCustomerEmailAddressString: String
}

Let surrounding types provide the rest of the story.

An unexplained number can be correct today and impossible to update consistently tomorrow.

private let maximumLoginAttempts = 3
if attempts >= maximumLoginAttempts {
  lockAccount()
}

if attempts >= 3 { lockAccount() }

A named constant explains why the number exists.

A name such as Manager or process gives little clue about ownership or outcome.

struct OrderValidator {
  func validate(_ order: Order) throws { /* … */ }
}

class DataManager {
  func process(_ order: Order) { /* … */ }
}

Specific names make responsibilities easier to see.

Mixed business decisions and implementation details are harder to change safely.

func submit(_ order: Order) async throws {
  try validate(order)
  try await orderGateway.save(order)
}

func submit(_ order: Order) async throws {
  guard order.total > 0 else { return }
  let data = try JSONEncoder().encode(order)
  try await client.post(data, to: "/orders")
}

Extract named steps when they clarify the main flow.

A growing parameter list invites swapped values and unclear call sites.

let window = ScheduleWindow(
  start: date, end: endDate,
  timeZone: zone, calendar: calendar
)
schedule(window)

schedule(start: date, end: endDate,
         zone: zone, calendar: calendar)

A value type is useful when it has a real domain meaning.

A read-like name that writes data surprises callers and complicates tests.

func isEligible(_ user: User) -> Bool {
  user.age >= 18
}
func recordEligibilityCheck(for user: User) {
  database.markChecked(user.id)
}

func isEligible(_ user: User) -> Bool {
  database.markChecked(user.id)
  return user.age >= 18
}

A query should answer; a command should act.

Deep nesting makes conditions and outcomes harder to connect.

guard let user, user.isActive,
      let email = user.email else { return }
send(to: email)

if let user = user {
  if user.isActive {
    if let email = user.email {
      send(to: email)
    }
  }
}

Keep the important path prominent.

The same rule in multiple flows can drift over time.

struct ShippingPolicy {
  static let freeThreshold = 50
  static func isFree(total: Decimal) -> Bool {
    total >= freeThreshold
  }
}

let canShip = order.total >= 50
let qualifiesForFreeShipping = cart.total >= 50

Deduplicate shared knowledge, not every similar line.

The goal is to keep variation local and understandable.

enum PaymentMethod {
  case card(CardDetails)
  case cash
}
switch paymentMethod {
case .card(let details): payWithCard(details)
case .cash: recordCashPayment()
}

if kind == "card" { /* … */ }
else if kind == "cash" { /* … */ }
// Repeated in several files

Use exhaustive switches for closed alternatives; use polymorphism when extension is genuinely needed.

A comment that repeats code adds reading without adding understanding.

let total = price + taxPolicy.tax(for: price)

// Add tax to the price
let total = price + price * 0.08

Make the operation explain itself.

Some intent cannot be inferred from implementation alone.

// The provider may serve stale reads immediately
// after an update; retry after its consistency window.
try await Task.sleep(for: .seconds(2))

// Wait two seconds
try await Task.sleep(for: .seconds(2))

Explain the reason a future maintainer might otherwise remove.

Scanning becomes faster when declaration order and whitespace signal structure.

func load() { decode() }
func save() { persist() }

private func decode() { /* … */ }
private func persist() { /* … */ }

func save() { persist() }
private func encode() -> Data { /* … */ }
func load() { decode() }

Use team conventions; readability matters more than a fixed line width.

A false comment can send the next engineer toward the wrong fix.

// The provider recommends at most three
// attempts to avoid duplicate processing.
retry(maxAttempts: 3)

// Retry forever until the server responds.
// oldRetryLoop()
retry(maxAttempts: 3)

Version control preserves old code; comments should describe current intent.

Callers should not be able to leave a domain object in an impossible state.

struct Wallet {
  private(set) var balance: Decimal
  mutating func withdraw(_ amount: Decimal) throws {
    guard amount <= balance else { throw WalletError.insufficientFunds }
    balance -= amount
  }
}

struct Wallet {
  var balance: Decimal
}
wallet.balance = -100

Let the owning type enforce its rules.

Long property chains couple a feature to several object shapes.

let fee = pricing.fee(for: order)

let fee = order.customer.account.plan.fee

Move decisions toward the abstraction that owns them.

Serialization and external APIs often need explicit, stable data shapes.

struct WeatherDTO: Decodable {
  let temperatureCelsius: Double
}
let forecast = Forecast(dto: response)

final class WeatherResponse {
  var temp: Double = 0
  func calculateForecast() { /* … */ }
}

Convert transport data into domain behavior at a clear boundary.

A vendor change should have a small, testable blast radius.

protocol Notifier {
  func send(_ message: Message) async throws
}
struct VendorNotifier: Notifier {
  func send(_ message: Message) async throws {
    try await sdk.send(message, channel: "push-v2")
  }
}

// Repeated throughout the app
sdk.send(message, channel: "push-v2")

Add a boundary when it protects a real dependency.

A focused test detects changed assumptions before they spread through the app.

func testVendorRejectsInvalidDates() {
  let result = sdk.parseDate("not-a-date")
  XCTAssertNil(result)
}

// Assume the SDK rejects invalid dates.
let date = sdk.parseDate(raw)

Test important vendor behavior, not the vendor’s entire implementation.

Callers need to distinguish an unavailable item from a failed operation.

func loadUser(id: UUID) throws -> User? {
  try database.fetch(id) // nil means not found
}

func loadUser(id: UUID) -> User? {
  try? database.fetch(id) // errors vanish
}

Do not hide operational failures behind an absent value.

An isolated low-level message is hard to act on in production.

catch {
  throw SyncError.uploadFailed(
    documentID: document.id,
    underlying: error
  )
}

catch {
  throw AppError.failed
}

Give the caller the context needed to respond.

Sentinel values and forced unwraps create surprising failure paths.

func search(_ text: String) -> [Item] {
  matches // [] is a valid result
}

func search(_ text: String) -> [Item]? {
  matches.isEmpty ? nil : matches
}

Let the type express the real contract.

Tests tied to internals resist safe refactoring.

func testExpiredCouponDoesNotDiscountTotal() {
  let total = checkout.total(using: expiredCoupon)
  XCTAssertEqual(total, 100)
}

func testCallsHelperTwice() {
  XCTAssertEqual(mock.helperCalls, 2)
}

A test should explain a rule a user or caller relies on.

Shared mutable fixtures cause intermittent, hard-to-reproduce failures.

func testCartContainsAddedItem() {
  var cart = Cart()
  cart.add(item)
  XCTAssertEqual(cart.count, 1)
}

func testA() { sharedCart.add(item) }
func testB() {
  XCTAssertEqual(sharedCart.count, 1)
}

A test should pass alone as well as in the suite.

Fast, deterministic tests support frequent safe changes.

func testExpiry() {
  let clock = TestClock(now: expiryDate)
  XCTAssertTrue(token.isExpired(at: clock.now))
}

func testExpiry() async throws {
  try await Task.sleep(for: .seconds(60))
  XCTAssertTrue(token.isExpired)
}

Control the environment when testing a rule.

The goal is a focused failure, not a literal assertion count.

func testDiscountedCheckoutTotal() {
  let receipt = checkout(discount: .tenPercent)
  XCTAssertEqual(receipt.subtotal, 100)
  XCTAssertEqual(receipt.discount, 10)
  XCTAssertEqual(receipt.total, 90)
}

func testCheckout() {
  XCTAssertEqual(total, 90)
  XCTAssertEqual(emailCount, 1)
  XCTAssertEqual(stock, 4)
}

Keep the test focused on one idea.

Short feedback loops prevent cleanup from drifting away from required behavior.

// Red: describe the missing discount rule.
// Green: implement the smallest correct change.
// Refactor: clarify names and remove duplication.

// Implement the whole feature, then write
// tests for the methods that already exist.

Keep each step small enough to understand.

Happy-path-only tests miss the conditions most likely to expose ambiguity.

func testTransferRejectsInsufficientFunds() {
  let result = transfer(100, from: walletWith50)
  XCTAssertEqual(result, .insufficientFunds)
}

func testTransfer() {
  XCTAssertTrue(transfer(10).succeeded)
}

Boundary tests teach future readers what the system promises.

A large type that mixes unrelated concerns makes every change risky.

struct TaxCalculator { /* … */ }
struct InvoiceRenderer { /* … */ }
struct ReceiptSender { /* … */ }

final class OrderManager {
  func calculateTax() { /* … */ }
  func renderPDF() { /* … */ }
  func sendEmail() { /* … */ }
}

Split by responsibility, not arbitrary file size.

Hidden construction makes a unit difficult to test or replace.

final class Checkout {
  let gateway: PaymentGateway
  init(gateway: PaymentGateway) {
    self.gateway = gateway
  }
}

final class Checkout {
  let gateway = LivePaymentGateway()
}

Make important dependencies visible.

Speculative layers create maintenance work before they protect anything.

struct DisplayName {
  static func forUser(_ user: User) -> String {
    "\(user.firstName) \(user.lastName)"
  }
}

protocol UserNameFormatterFactoryProvider {
  func make() -> UserNameFormatterFactory
}

Prefer the simplest design that meets today’s needs.

Small steps make regressions easier to locate and undo.

// 1. Characterize existing behavior.
// 2. Extract parsing behind a boundary.
// 3. Switch one caller, then repeat.

// Rewrite parser, storage, and UI in one PR
replaceEverything()

Make it work, make it clear, and keep tests green.

A grab bag of unrelated operations has no stable reason to change.

struct AvatarEditor { /* image behavior */ }
struct TaxCalculator { /* tax policy */ }

final class ProfileService {
  var avatar: Image?
  func cropImage() { /* … */ }
  func calculateTax() { /* … */ }
}

Cohesion is about shared purpose, not a tiny method count.

Minimizing class count first can hide responsibilities and raise change cost.

// Separate only the concepts that have
// different rules or reasons to change.
struct Invoice { /* … */ }
struct TaxPolicy { /* … */ }

// One giant type avoids extra classes.
final class Everything { /* … */ }

Simplicity means easy to understand and change.

Incremental care prevents a backlog of avoidable confusion.

let amountDue = invoice.amountDue
// Add a regression test for the repaired rule.

// Fix the bug; preserve the misleading name.
let x = invoice.amountDue

Small, verified cleanup compounds over time.

Uncontrolled mutation creates races that are hard to reproduce.

actor Counter {
  private(set) var value = 0
  func increment() { value += 1 }
}

final class Counter {
  var value = 0
  func increment() { value += 1 }
}

Give concurrent mutation an explicit owner or synchronization boundary.

A multi-step async operation is not automatically atomic when other work can run between steps.

let userID = currentUser.id
let data = try await api.load(userID)
guard currentUser.id == userID else { return }
profile = data

let user = currentUser
let data = try await api.load(user.id)
profile = data

Protect against stale async results.

Leaked tasks and stale callbacks can outlive the feature that started them.

func search(_ query: String) {
  searchTask?.cancel()
  searchTask = Task {
    let response = try await api.search(query)
    try Task.checkCancellation()
    results = response
  }
}

func search(_ query: String) {
  Task { results = try await api.search(query) }
}

Test rapid retries, cancellation, and lifecycle edges.

Mixing synchronization and domain logic makes both harder to reason about.

struct CartPricing {
  func total(for items: [Item]) -> Decimal {
    items.reduce(0) { $0 + $1.price }
  }
}
actor CartStore { /* coordinates items */ }

actor Cart {
  func total() async -> Decimal {
    // Fetch policy while summing every line
  }
}

Concurrency is a boundary around behavior, not the behavior itself.

Concurrency bugs often require an unfavorable order of events.

func testOldResponseCannotReplaceNewQuery() async {
  await api.complete(newQuery, with: newResult)
  await api.complete(oldQuery, with: oldResult)
  XCTAssertEqual(viewModel.result, newResult)
}

func testLoad() async {
  await viewModel.load()
  XCTAssertNotNil(viewModel.result)
}

Control scheduling in tests so a race is repeatable.