---
source: ~/DuckDuckGo/apple-browsers.git/main/.cursor/rules/code-style.mdc
confidence: 0.9
namespace: work
last_synced: 2026-04-28
alwaysApply: true
---

# Swift Code Style Guide

*This style guide is based on the [official iOS style guide](iOS/styleguide/STYLEGUIDE.md) and incorporates DuckDuckGo-specific patterns and requirements.*

## Correctness

**Strive to make your code compile without warnings.** This rule informs many style decisions such as using `#selector` types instead of string literals.

## SwiftLint

We use [SwiftLint](https://github.com/realm/SwiftLint) for enforcing Swift style and conventions. See the [SwiftLint configuration](.swiftlint.yml) for specific rules.

**Key SwiftLint settings**:
- Line length: 150 characters (not the default 100)
- Force cast/try: warnings (not errors for pragmatic development)
- Identifier naming: flexible for single-letter variables in closures

## Naming Conventions

Follow the [Swift API Design Guidelines](https://swift.org/documentation/api-design-guidelines/) with these key principles:

### Core Principles
- **Clarity at the call site** over brevity
- **Use camelCase** (not snake_case)
- **UpperCamelCase** for types and protocols
- **lowerCamelCase** for everything else
- **Include all needed words** while omitting needless words
- **Use names based on roles**, not types

### Type Names
```swift
// ✅ CORRECT: Descriptive, UpperCamelCase
class UserAuthenticationManager { }
struct BookmarkItem { }
enum NavigationState { }
protocol DataSourceProtocol { }

// ❌ INCORRECT: Too generic
class Manager { }
struct Data { }
```

### Variable and Function Names
```swift
// ✅ CORRECT: Descriptive lowerCamelCase
let maximumRetryCount = 3
var isLoading = false
func fetchUserData() { }

// Boolean properties should read like assertions
var isEnabled: Bool
var hasCompleted: Bool
var canDelete: Bool

// ❌ INCORRECT: Abbreviations and unclear names
let usrMgr = UserManager()
func calcTotal() { }
```

### Protocol Naming
```swift
// ✅ CORRECT: Capability protocols end in -able, -ible, -ing
protocol Loadable { }
protocol Refreshable { }
protocol UserAuthenticating { }

// ✅ CORRECT: Type protocols are nouns
protocol DataSource { }
protocol Delegate { }
```

### Method Naming Patterns
```swift
// ✅ CORRECT: Method naming patterns
// Factory methods begin with "make"
func makeLocationManager() -> CLLocationManager

// Verb methods follow -ed, -ing rule for non-mutating
func sorted() -> [Element]  // non-mutating
func sort()                 // mutating

// Boolean methods read like assertions
func canDelete() -> Bool
func hasCompleted() -> Bool
```

### Delegate Methods
When creating custom delegate methods, the **unnamed first parameter should be the delegate source**:

```swift
// ✅ CORRECT: Delegate pattern
func namePickerView(_ namePickerView: NamePickerView, didSelectName name: String)
func namePickerViewShouldReload(_ namePickerView: NamePickerView) -> Bool

// ❌ INCORRECT: Missing source parameter
func didSelectName(namePicker: NamePickerViewController, name: String)
func namePickerShouldReload() -> Bool
```

### Use Type Inferred Context
Use compiler inferred context to write shorter, clear code:

```swift
// ✅ CORRECT: Type inferred context
let selector = #selector(viewDidLoad)
view.backgroundColor = .red
let toView = context.view(forKey: .to)
let view = UIView(frame: .zero)

// ❌ INCORRECT: Redundant type information
let selector = #selector(ViewController.viewDidLoad)
view.backgroundColor = UIColor.red
let toView = context.view(forKey: UITransitionContextViewKey.to)
let view = UIView(frame: CGRect.zero)
```

### Generics
Generic type parameters should be **descriptive, UpperCamelCase names**:

```swift
// ✅ CORRECT: Descriptive generic names
struct Stack<Element> { ... }
func write<Target: OutputStream>(to target: inout Target)
func swap<T>(_ a: inout T, _ b: inout T)  // T is acceptable when no meaningful relationship

// ❌ INCORRECT: Non-descriptive or wrong case
struct Stack<T> { ... }
func write<target: OutputStream>(to target: inout target)
```

### Language
Use **US English spelling** to match Apple's API:

```swift
// ✅ CORRECT: US English
let color = "red"

// ❌ INCORRECT: British English
let colour = "red"
```

## Code Organization

### File Structure
```swift
// 1. Import statements (minimal - only what's needed)
import UIKit
import Combine

// 2. Protocol definitions
protocol FeatureDelegate: AnyObject {
    func featureDidUpdate()
}

// 3. Main type declaration
class FeatureViewController: UIViewController {
    // Properties first
    private let viewModel: FeatureViewModel
    
    // Lifecycle methods
    override func viewDidLoad() {
        super.viewDidLoad()
        setupUI()
    }
    
    // Private methods
    private func setupUI() { }
}

// 4. Extensions for protocol conformance
// MARK: - UITableViewDataSource
extension FeatureViewController: UITableViewDataSource {
    // Protocol methods
}
```

### Protocol Conformance
**Prefer separate extensions** for protocol conformance to keep related methods grouped:

```swift
// ✅ CORRECT: Separate extensions
class MyViewController: UIViewController {
    // class implementation
}

// MARK: - UITableViewDataSource
extension MyViewController: UITableViewDataSource {
    // table view data source methods
}

// MARK: - UIScrollViewDelegate
extension MyViewController: UIScrollViewDelegate {
    // scroll view delegate methods
}

// ❌ INCORRECT: All in main class declaration
class MyViewController: UIViewController, UITableViewDataSource, UIScrollViewDelegate {
    // all methods mixed together
}
```

### Minimal Imports
**Import only the modules a source file requires**:

```swift
// ✅ CORRECT: Minimal imports
import UIKit
var view: UIView
var deviceModels: [String]

// ✅ CORRECT: Foundation when UIKit not needed
import Foundation
var deviceModels: [String]

// ❌ INCORRECT: Unnecessary imports
import UIKit
import Foundation  // UIKit already includes Foundation
var view: UIView
var deviceModels: [String]
```

### Remove Unused Code
**Remove unused (dead) code**, including Xcode template code:

```swift
// ✅ CORRECT: Keep only implemented methods
override func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
    return Database.contacts.count
}

// ❌ INCORRECT: Template code and unused methods
override func didReceiveMemoryWarning() {
    super.didReceiveMemoryWarning()
    // Dispose of any resources that can be recreated.
}

override func numberOfSections(in tableView: UITableView) -> Int {
    // #warning Incomplete implementation, return the number of sections
    return 1
}
```

## Formatting and Style

### Line Breaks and Length
- **Line margin: 150 characters** (not the default 100)
- **Long lines should be wrapped** at around 150 characters
- **Avoid trailing whitespace** at ends of lines
- **Add single newline** at end of each file

### Spacing
- **Indent using 4 spaces** rather than tabs
- **Method braces open on same line**, close on new line
- **One blank line between methods**
- **No blank lines after opening brace or before closing brace**

```swift
// ✅ CORRECT: Spacing and braces
if user.isHappy {
    // Do something
} else {
    // Do something else
}

// ❌ INCORRECT: Wrong brace placement
if user.isHappy
{
    // Do something
}
else {
    // Do something else
}
```

### Colons
**Colons have no space on left, one space on right**. Exceptions: ternary operator `? :`, empty dictionary `[:]`, `#selector` syntax:

```swift
// ✅ CORRECT: Colon spacing
class TestDatabase: Database {
    var data: [String: CGFloat] = ["A": 1.2, "B": 3.2]
}

// ❌ INCORRECT: Wrong colon spacing
class TestDatabase : Database {
    var data :[String:CGFloat] = ["A" : 1.2, "B":3.2]
}
```

### Function Parameters
**Closing parentheses should not appear on line by themselves**:

```swift
// ✅ CORRECT: Closing parenthesis placement
let user = try await getUser(
    for: userID,
    on: connection)

// ❌ INCORRECT: Closing parenthesis on own line
let user = try await getUser(
    for: userID,
    on: connection
)
```

## Function Declarations

### Short Functions
**Keep short function declarations on one line**:

```swift
// ✅ CORRECT: Short function on one line
func reticulateSplines(spline: [Double]) -> Bool {
    // implementation
}
```

### Long Function Signatures
**For functions with long signatures, put each parameter on new line**:

```swift
// ✅ CORRECT: Long signature formatting
func reticulateSplines(spline: [Double],
                      adjustmentFactor: Double,
                      translateConstant: Int,
                      comment: String) -> Bool {
    // implementation
}
```

### Return Types
**Use `Void` for closure/function outputs, `()` for inputs**:

```swift
// ✅ CORRECT: Return type formatting
func updateConstraints() -> Void {
    // implementation
}

typealias CompletionHandler = (result) -> Void

// ❌ INCORRECT: Wrong return type syntax
func updateConstraints() -> () {
    // implementation
}

typealias CompletionHandler = (result) -> ()
```

## Function Calls

**Mirror function declaration style at call sites**:

```swift
// ✅ CORRECT: Single line when it fits
let success = reticulateSplines(splines)

// ✅ CORRECT: Multi-line when wrapped
let success = reticulateSplines(
    spline: splines,
    adjustmentFactor: 1.3,
    translateConstant: 2,
    comment: "normalize the display")
```

## Closure Expressions

### Trailing Closure Syntax
**Use trailing closure syntax only for single closure at end**:

```swift
// ✅ CORRECT: Trailing closure usage
UIView.animate(withDuration: 1.0) {
    self.myView.alpha = 0
}

UIView.animate(withDuration: 1.0, animations: {
    self.myView.alpha = 0
}, completion: { finished in
    self.myView.removeFromSuperview()
})

// ❌ INCORRECT: Trailing closure with multiple closures
UIView.animate(withDuration: 1.0, animations: {
    self.myView.alpha = 0
}) { f in
    self.myView.removeFromSuperview()
}
```

### Single-Expression Closures
**Use implicit returns for single-expression closures**:

```swift
// ✅ CORRECT: Implicit return
attendeeList.sort { a, b in
    a > b
}
```

### Chained Methods
**Format chained methods for clarity**:

```swift
// ✅ CORRECT: Chained methods - compact when clear
let value = numbers.map { $0 * 2 }.filter { $0 % 3 == 0 }.index(of: 90)

// ✅ CORRECT: Chained methods - multi-line when complex
let value = numbers
    .map { $0 * 2 }
    .filter { $0 > 50 }
    .map { $0 + 10 }
```

## Types and Constants

### Native Types
**Always use Swift's native types** when available:

```swift
// ✅ CORRECT: Native Swift types
let width = 120.0                    // Double
let widthString = "\(width)"         // String

// ❌ INCORRECT: Objective-C types
let width: NSNumber = 120.0          // NSNumber
let widthString: NSString = width.stringValue  // NSString
```

### Constants vs Variables
**Use `let` by default, change to `var` only when compiler complains**:

```swift
// ✅ CORRECT: Type properties for constants
enum Math {
    static let e = 2.718281828459045235360287
    static let root2 = 1.41421356237309504880168872
}

let hypotenuse = side * Math.root2

// ❌ INCORRECT: Global constants
let e = 2.718281828459045235360287  // pollutes global namespace
let root2 = 1.41421356237309504880168872
```

### Type Inference
**Prefer compact code and let compiler infer types**:

```swift
// ✅ CORRECT: Type inference
let message = "Click the button"
let currentBounds = computeViewBounds()
var names = ["Mic", "Sam", "Christine"]
let maximumWidth: CGFloat = 106.5  // Specify when needed

// ❌ INCORRECT: Unnecessary type annotations
let message: String = "Click the button"
let currentBounds: CGRect = computeViewBounds()
```

### Empty Collections
**Use type annotation for empty arrays and dictionaries**:

```swift
// ✅ CORRECT: Type annotation for empty collections
var names: [String] = []
var lookup: [String: Int] = [:]

// ❌ INCORRECT: Constructor syntax
var names = [String]()
var lookup = [String: Int]()
```

### Syntactic Sugar
**Prefer shortcut type declarations**:

```swift
// ✅ CORRECT: Syntactic sugar
var deviceModels: [String]
var employees: [Int: String]
var faxNumber: Int?

// ❌ INCORRECT: Full generics syntax
var deviceModels: Array<String>
var employees: Dictionary<Int, String>
var faxNumber: Optional<Int>
```

## Optionals

### Optional Declarations
**Use `?` for optional types, `!` only when you know initialization timing**:

```swift
// ✅ CORRECT: Optional usage
var subview: UIView?
var volume: Double?

// Use ! only for outlets that initialize in viewDidLoad
@IBOutlet weak var tableView: UITableView!
```

### Optional Binding
**Shadow original names in optional binding**:

```swift
// ✅ CORRECT: Shadow original name
if let subview = subview, let volume = volume {
    // do something with unwrapped subview and volume
}

// ❌ INCORRECT: Different names for unwrapped values
if let unwrappedSubview = optionalSubview {
    if let realVolume = volume {
        // do something with unwrappedSubview and realVolume
    }
}
```

### Optional Chaining vs Binding
**Use optional chaining for single access, binding for multiple operations**:

```swift
// ✅ CORRECT: Optional chaining for single access
textContainer?.textLabel?.setNeedsDisplay()

// ✅ CORRECT: Optional binding for multiple operations
if let textContainer = textContainer {
    // do many things with textContainer
}
```

## Memory Management

### Reference Cycles
**Prevent reference cycles with `weak` and `unowned` references.**

**Example:** See [memory-management.swift](code-style/memory-management.swift)

### Lazy Initialization
**Use lazy initialization for fine-grained control**:

```swift
// ✅ CORRECT: Lazy initialization
lazy var locationManager = makeLocationManager()

private func makeLocationManager() -> CLLocationManager {
    let manager = CLLocationManager()
    manager.desiredAccuracy = kCLLocationAccuracyBest
    manager.delegate = self
    manager.requestAlwaysAuthorization()
    return manager
}
```

## Access Control

### Access Control Order
**Access control comes first, except for `static` and attributes**:

```swift
// ✅ CORRECT: Access control ordering
private let message = "Great Scott!"

class TimeMachine {
    private dynamic lazy var fluxCapacitor = FluxCapacitor()
    @IBAction private func activate() { }
    static private let timeConstant = 88.0
}

// ❌ INCORRECT: Wrong ordering
fileprivate let message = "Great Scott!"

class TimeMachine {
    lazy dynamic private var fluxCapacitor = FluxCapacitor()
}
```

### Private vs Fileprivate
**Prefer `private` to `fileprivate`**; use `fileprivate` only when compiler requires it.

## Control Flow

### Loop Style
**Prefer `for-in` style over `while-condition-increment`**:

```swift
// ✅ CORRECT: for-in style
for _ in 0..<3 {
    print("Hello three times")
}

for (index, person) in attendeeList.enumerated() {
    print("\(person) is at position #\(index)")
}

// ❌ INCORRECT: while style
var i = 0
while i < 3 {
    print("Hello three times")
    i += 1
}
```

### Ternary Operator
**Use ternary operator only when it increases clarity**:

```swift
// ✅ CORRECT: Simple ternary usage
let value = 5
result = value != 0 ? x : y

let isHorizontal = true
result = isHorizontal ? x : y

// ❌ INCORRECT: Complex nested ternary
result = a > b ? x = c > d ? c : d : y
```

### Golden Path
**Use the "golden path" pattern - don't nest `if` statements**:

```swift
// ✅ CORRECT: Golden path with guard
func computeFFT(context: Context?, inputData: InputData?) throws -> Frequencies {
    guard let context = context else {
        throw FFTError.noContext
    }
    guard let inputData = inputData else {
        throw FFTError.noInputData
    }
    
    // use context and input to compute the frequencies
    return frequencies
}

// ❌ INCORRECT: Nested if statements
func computeFFT(context: Context?, inputData: InputData?) throws -> Frequencies {
    if let context = context {
        if let inputData = inputData {
            // use context and input to compute the frequencies
            return frequencies
        } else {
            throw FFTError.noInputData
        }
    } else {
        throw FFTError.noContext
    }
}
```

### Compound Guard Statements
**Use compound guard for multiple optionals**:

```swift
// ✅ CORRECT: Compound guard
guard 
    let number1 = number1,
    let number2 = number2,
    let number3 = number3 
else {
    fatalError("impossible")
}

// ❌ INCORRECT: Nested optional binding
if let number1 = number1 {
    if let number2 = number2 {
        if let number3 = number3 {
            // do something with numbers
        }
    }
}
```

## Class and Struct Definitions

### Example Well-Styled Class
```swift
final class Circle: Shape {
    var x: Int, y: Int
    var radius: Double
    var diameter: Double {
        get {
            radius * 2
        }
        set {
            radius = newValue / 2
        }
    }
    
    init(x: Int, y: Int, radius: Double) {
        self.x = x
        self.y = y
        self.radius = radius
    }
    
    convenience init(x: Int, y: Int, diameter: Double) {
        self.init(x: x, y: y, radius: diameter / 2)
    }
    
    override func area() -> Double {
        Double.pi * radius * radius
    }
}

extension Circle: CustomStringConvertible {
    var description: String {
        "center = \(centerString) area = \(area())"
    }
    
    private var centerString: String {
        "(\(x),\(y))"
    }
}
```

### Use of Self
**Avoid using `self` unless required by compiler**:

```swift
// ✅ CORRECT: Self only when required
class PhotoViewController: UIViewController {
    var image: UIImage
    
    init(image: UIImage) {
        self.image = image  // Required to disambiguate
        super.init(nibName: nil, bundle: nil)
    }
    
    func setupImageView() {
        imageView.image = image  // self not needed
    }
}
```

### Computed Properties
**Omit get clause for read-only computed properties**:

```swift
// ✅ CORRECT: Implicit get for read-only
var diameter: Double {
    radius * 2
}

// ❌ INCORRECT: Unnecessary get clause
var diameter: Double {
    get {
        return radius * 2
    }
}
```

### Final
**Use `final` when inheritance is not intended**:

```swift
// ✅ CORRECT: Final for utility classes
final class Box<T> {
    let value: T
    init(_ value: T) {
        self.value = value
    }
}
```

## DuckDuckGo-Specific Patterns

### Design System Integration (MANDATORY)

**ALWAYS use DesignResourcesKit** for colors, typography, and icons.

**Example:** See [design-system-integration.swift](code-style/design-system-integration.swift)

### Dependency Injection Pattern
**Use AppDependencyProvider for dependency injection.**

**Example:** See [dependency-injection.swift](code-style/dependency-injection.swift)

### Async/Await Patterns
**Example:** See [async-await-pattern.swift](code-style/async-await-pattern.swift)

### Property Wrappers
**Example:** See [property-wrappers.swift](code-style/property-wrappers.swift)

## Comments and Documentation

### When to Comment
**Use comments to explain WHY, not WHAT**:

```swift
// ✅ CORRECT: Explains why
// We delay the animation to avoid conflicting with the previous transition
DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) {
    self.animateTransition()
}

// ❌ INCORRECT: Explains what (obvious from code)
// Set the background color to red
view.backgroundColor = .red
```

### Comment Style
**Prefer double/triple-slash over C-style comments**:

```swift
// ✅ CORRECT: Swift-style comments
// This is a comment
/// This is a documentation comment

// ❌ INCORRECT: C-style comments
/* This is a comment */
```

## String Literals

### Multi-line Strings
**Use multi-line string syntax for long strings**:

```swift
// ✅ CORRECT: Multi-line string formatting
let message = """
    You cannot charge the flux \
    capacitor with a 9V battery.
    You must use a super-charger \
    which costs 10 credits. You currently \
    have \(credits) credits available.
    """

// ❌ INCORRECT: Concatenation or inline text
let message = """You cannot charge the flux \
    capacitor with a 9V battery.
    You must use a super-charger \
    which costs 10 credits. You currently \
    have \(credits) credits available.
    """
```

## Prohibited Patterns

### No Emoji
**Do not use emoji in code** - it creates unnecessary friction:

```swift
// ❌ FORBIDDEN: Emoji in code
let isHappy = true 😀
func celebrate() 🎉 { }

// ✅ CORRECT: Clear, text-based names
let isHappy = true
func celebrate() { }
```

### No Color/Image Literals
**Do not use `#colorLiteral` or `#imageLiteral`** - they're hard to read and maintain:

```swift
// ❌ FORBIDDEN: Literals
let color = #colorLiteral(red: 1, green: 0, blue: 0, alpha: 1)
let image = #imageLiteral(resourceName: "icon")

// ✅ CORRECT: Explicit constructors (but prefer DesignResourcesKit)
let color = UIColor(red: 1, green: 0, blue: 0, alpha: 1)
let image = UIImage(named: "icon")

// ✅ BEST: DesignResourcesKit
let color = UIColor(designSystemColor: .accent)
let image = DesignSystemImages.Color.Size24.bookmark
```

### No Parentheses Around Conditionals
**Don't use unnecessary parentheses**:

```swift
// ✅ CORRECT: No parentheses needed
if name == "Hello" {
    print("World")
}

// ❌ INCORRECT: Unnecessary parentheses
if (name == "Hello") {
    print("World")
}
```

### No Semicolons
**Swift doesn't require semicolons** - don't use them:

```swift
// ✅ CORRECT: No semicolons
let swift = "not a scripting language"

// ❌ INCORRECT: Unnecessary semicolons
let swift = "not a scripting language";
```

## Error Handling and Assertions

### Fatal Errors
**Use `fatalError()` when app reaches unrecoverable state**:

```swift
// ✅ CORRECT: Fatal error for impossible states
guard let viewController = storyboard.instantiateViewController(withIdentifier: "Main") as? MainViewController else {
    fatalError("Failed to instantiate MainViewController from storyboard")
}
```

### Assertions
**Use `assert()` and `assertionFailure()` for recoverable but unexpected states**:

```swift
// ✅ CORRECT: Assert for development debugging
func processItems(_ items: [Item]) {
    assert(!items.isEmpty, "Items array should not be empty")
    
    // Handle empty array gracefully in release builds
    guard !items.isEmpty else { return }
    
    // Process items...
}
```

## Logging

**Use unified logging system** for all logging.

**Example:** See [logging-pattern.swift](code-style/logging-pattern.swift)

**See [Logging Guidelines](logging-guidelines.md) for comprehensive logging patterns.**

## Unit Test Naming

**Use "when/then" convention for test names**:

```swift
// ✅ CORRECT: When/then test naming
func testWhenUrlIsNotATrackerThenMatchesIsFalse() { }
func testWhenUserTapsBookmarkButtonThenBookmarkIsAdded() { }
func testWhenNetworkFailsThenErrorIsDisplayed() { }

// ❌ INCORRECT: Unclear test names
func testBookmarks() { }
func testNetworking() { }
```

## Functions vs Methods

**Prefer methods over free functions** for discoverability:

```swift
// ✅ CORRECT: Methods are easily discoverable
let sorted = items.mergeSorted()
rocket.launch()

// ❌ INCORRECT: Free functions are hard to discover
let sorted = mergeSort(items)
launch(&rocket)

// ✅ ACCEPTABLE: Free functions that feel natural
let tuples = zip(a, b)
let value = max(x, y, z)
```

---

**Remember**: This style guide ensures consistency across the DuckDuckGo browser codebase. When in doubt, prioritize clarity and follow the patterns established in existing code.