Home

Awesome

Swift Style Guide

Table Of Contents

Overview

This is Prolific's style guide for writing code in Swift. The purpose of this guide is to develop a universal standard for Swift code that makes our codebases consistent and easy to read. This guide aims for consistent and clean code written in Swift in line with Apple and the general community.

The standards have been influenced by:

Contributing

If you wish to contribute, feel free to submit a pull request or file an issue on this repo. In the pull request, be sure to discuss what problem you are intending to solve and the rationale to do so. When submitting a pull request, consider:

Make sure to consider the resources in the open-source Swift repo; specifically, read through the various proposals for new language features as well as the most-commonly rejected proposals in order to guide your design principals.

Linter

In order to automate many of the rules here, we recommend using our fork of Swiftlint in your Swift codebase. While the main fork of Swiftlint is based around the GitHub style guide for Swift, our fork has additional rules and corrections for rules specific to our style guide that you will not find in the GitHub one.

Standards

Naming Conventions

The Apple Swift API design guidelines promote clarity over brevity. Code should be concise, readable and clear at the point of use. However, having compact code that sacrifices clarity is a non-goal.

Types

Write all type names with UpperCamelCase, function and variable names with lowerCamelCase.

class MyClass { }
protocol MyProtocol { }
func myFunction() { }
var myVariable: String

Avoid acronyms and abbreviations for clarity and readability. If you have to use an acronym, use upper case.

productURL = NSURL()
userID = "12345"

Protocols

Protocol names describing something should be a noun: Collection, Element. Protocol names describing an ability should end with “ing” or “able”: Evaluatable, Printable, Formatting.

Enums

Enum cases start with lowerCamelCase.

enum Color {
    case red
    case blue
    case green
    case lightBlue
}

Functions

Name your function with words that describe its behavior. Here is an example with a function that removes an element at an index x.

Preferred:

func remove(at index: Index) -> Element

Not Preferred:

func remove(index: Index) -> Element

Rationale: It is better to specify that we are removing the element at the given index, and we are not trying to remove the given parameter itself, to make the behavior of the function very clear.

Avoid unnecessary words in the function name.

Preferred:

func remove(_ element: Element) -> Element?

Not Preferred:

func removeElement(_ element: Element) -> Element?

Rationale: It makes the code clearer and more concise. Adding extra unnecessary words will make the code harder to read and understand.

Name your functions based on their side effects and behaviors.

When the function can be described by a verb, use an imperative verb for the mutating function and apply “ed” or “ing” to the nonmutating function:

Name functions to be read as a sentence according to their side effects.

Preferred:

x.insert(y, at: z)          // x, insert y at z
x.subViews(havingColor: y)  // x's subviews having color y
x.capitalizingNouns()       // x, capitalizing nouns

Not Preferred:

x.insert(y, position: z)
x.subViews(color: y)
x.nounCapitalize()

Empty Return Types

When specifying return type for functions, methods or closures that return no value, favor the type alias Void over empty tuple ().

Preferred:

func performTask(_ completion: @escaping (Bool) -> Void)

Not Preferred:

func performTask(_ completion: @escaping (Bool) -> ())

File structure

You should not define multiple public/internal types (ie class, struct, enum) in the same file; each type should have its own file.

The following list should be the standard organization of all your Swift files, in this specific order:

Before the type declaration:

Inside the type declaration:

After the type declaration:

Each section above should be organized by accessibility:

When implementing a protocol you should create an extension of your class that lives in the same file to separate the core logic of your class and your protocol implementation.

Enum & Protocol

All enums should live in their own file, except in cases where the enum is declared as private. In cases where the enum is declared private, declare the enum at the top of the file, above the type declaration.

Rationale: With enum and protocol types Swift allows defining functions and extensions. Because of that these types can become complex which is why they should be defined in their own file.

Usage of MARK / TODO / FIXME

To help organize your files you may want to use pragma marks to clearly separate your functions, properties and extensions. For extensions, use one MARK per extension. For example, // MARK: UITableViewDelegate Functions instead of // MARK: Extensions.

Xcode is also able to display TODO and FIXME tags directly in the source navigator, you should consider using them to find your notes inside your files.

// TODO: implement this feature

// FIXME: fix it it's not working

Other conventional comment tags, such as NOTE are not recognized by Xcode.

Types

Prefer Swift native types over Objective-C types when possible. Because Swift types bridge to Objective-C, you should avoid types like NSString and NSNumber in favor of Int or String.

Rationale: Avoid subclassing NSObject or using the @objc flag unless it is required to implement an NSObjectProtocol type. Subclassing NSObject or using the @objc flag automatically creates an Objective-C object that uses dynamic dispatch over the preferred static of Swift which can impact the performance of the app.

Preferred:

class MyClass {
...
}

Not preferred:

@objc class MyClass {
...
}

If you need functionality from an Objective-C type that is not available in its corresponding Swift type (for instance, needing an NSString function that is not available on String), cast your Swift raw type to the corresponding Objective-C type instead of declaring the type as the Objective-C type.

Preferred:

let scale = 5.0
let scaleString = (5.0 as NSNumber).stringValue
let scaleInt = Int(scale)

Not preferred:

let scale: NSNumber = 5.0
let scaleString = scale.stringValue
let scaleInt = scale.integerValue

Always use Swift equivalent of an Objective-C function whenever possible. For example when manipulating a CGRect variable:

Preferred:

let rect = CGRect()
let width = rect.width
let height = rect.height

Not preferred:

let rect = CGRect()
let width = CGRectGetWidth(rect)
let height = CGRectGetHeight(rect)

Rationale: Objective-C functions are making the code less readable, also using Swift equivalents will always help transitioning from a Swift version to another.

Type Declarations

When declaring types, the colon should be placed immediately after the identifier followed by one space and the type name.


var intValue: Int

// Do NOT do this
var intValue : Int

In all use-cases, the colon should be associated with the left-most item with no spaces preceding and one space afterwards:

let myDictionary: [String: AnyObject] = ["String": 0]

typealias

Typealias declarations should precede any other type declaration.

// typealias ClosureType = (ParameterTypes) -> (ReturnType)
typealias AgeAndNameProcessor = (Int, String) -> Void

var intValue: Int

class Object {

	private var someString = ""

	func returnOne() -> Int {
		return 1
	}

}

If declaring a typealias for protocol conformance, it should be declared at the top of the type declaration, before anything else.

protocol Configurable {

    associatedtype InputData

    func configure(data: InputData) -> Void

}

class ExampleWillNeed {

    var x: String = ""
    var y: String = ""

}

class Example: Configurable {

    typealias InputData = ExampleWillNeed

    var a: String = ""
    var b: String = ""

    func configure(data: InputData)  {
        a = data.x
        b = data.y
    }

}

Type Inference

Prefer letting the compiler infer the type instead of explicitly stating it, wherever possible:

var max = 0 		// Int
var name = "John" 	// String
var rect = CGRect()	// CGRect

// Do not do:

var max: Int = 0
var name: String = "John"
var rect: CGRect = CGRect()

// Ok since the inferred type is not what we wanted:

var max: Hashable = 0 // Compiler would infer Int, but we only want it to be hashable
var name: String? = "John" // Compiler would infer this not to be optional, but we may need to nil it out later.

Rationale The compiler is pretty smart, and we should utilize it where necessary. It is generally obvious what the type is going to be in the instances above, so unless we need to be more explicit (as in the last examples above), it is better to omit unneeded words.

Statement Termination

Unlike Objective-C, omit the use of ; to terminate statements. Instead, simply use new lines to indicate the end of a statement.

let myVar = 0
doSomething(myVar)

return

Avoid multiple statements on a single line.

guard let obj = myObj else { print("Something went wrong"); return; } // Wrong! Instead, place each item on its own line.

Variable Declaration

For declaring variables, favor let instead of var unless you need a mutable object or container.

func formatDate(date: NSDate) -> String {
    let dateFormatter = NSDateFormatter() // In this case, use `let` since the variable `dateFormatter` never changes once set
    dateFormatter.dateStyle = .ShortStyle
    return dateFormatter.stringFromDate(date)
}

func arrays() {
    let array = ["Hello", "Ciao", "Aloha"] // use let here since this is an immutable container

    var mutableArray = [String]() // Use var here since this container is mutable
    mutableArray.append("Farewell")
    mutableArray.append("Arrivederci")
}

Self

Never use the self modifier except in cases where it is necessary for the compiler or to alleviate conflicts with other variable declarations.


class Object {
	private var name = ""

	func useName() {
		// Let self be implied when it can be understood.
		otherObject.doSomethingWithName(name)
		setName("Will Smith")
	}

	func setName(name: String) {
		// Use self here to prevent conflicts with the `name` parameter being passed.
		self.name = name
	}

	func setNameAsync(newName: String) {
		// Use implicit self outside closures...
		otherObject.doSomethingWithName(name, then: {
			// .. but within, you must use self to ease the compiler.
			self.setName("Jason")
		})
	}
}

Rationale: The idea behind this is that implicit use of self makes the conditions where you must use self (for instance, within closures) much more apparent and will make you think more on the reasons why you are using it. In closures, think about: should self be weak instead of strong? Apple has even rejected a request to enforce use of self for this reason, among others.

Bracket Syntax

For brackets, prefer the Xcode-default syntax of having the opening brace be on the same line as the statement opening it:

final class MyObject {
}

enum MyEnum {
}

func doSomething() {
}

if true == false {
}

let doSomething: () -> Void = {
}

For type declarations, include a single space between the type declaration and the first item implemented within it:

final class MyObject {

	let value = 0

In addition, include a space before the type declaration's closing bracket:

final class MyObject {

	let value = 0

	func doSomething() {
		value += 1
	}

}

This also applies to extension declarations:

extension MyObject {

	func doAnotherThing() {
		...
	}

}

Do not include this extra space in function declarations:

func doSomething() {
	let value = 0
}

Rationale: Simply put, this is the Xcode default and standard, and it's not worth fighting. This keeps things consistent across the board and makes our lives as developers considerably easier.

Force Unwrap

Unless there is a situation that absolutely calls for it, usage of the force-unwrap operator (!) should be minimized, if not eliminated all together. With the many and varied ways of unwrapping optionals, it is safer and simpler to declare variables as optional and unwrap them when needing their values than it is to force-unwrap them and potentially introduce runtime errors into the code base.


if let text = self.textLabel?.text {
    doSomethingWithText(text)
}

If you are interoping from Objective-C and the declaration automatically translates into force-unwrapped parameters, replace them with ? parameters instead.

The one exception to this rule are IBOutlets. @IBOutlets may be declared using ! so long as they are expected to exist for the lifetime of the view controller object:

@IBOutlet private weak var textLabel: UILabel!

Error Handling

The emergence of try / catch in Swift 2 has added powerful ways to define and return errors when something fails. The emergence of ErrorType as well for defining errors makes error definitions much more convenient over the cumbersome NSError. Because of this, for functions that can have multiple points of failure, you should always define it as throws and return a well-defined ErrorType.

Consider the following contrived example:


func multiplyEvensLessThan10(evenNumber: Int) -> Int? {
	guard evenNumber % 2 == 0 && evenNumber < 10 else {
		return nil
	}

	return evenNumber * 2
}

The function above fails because it only expects evens less than 10 and returns an optional if that is violated. While this works and is simple, it is more Objective-C than Swift in its composition. The caller may not know which parameter they violated. For Swift, instead consider refactoring it as follows:


enum NumberError: ErrorType {
	case notEven
	case tooLarge
}

func multiplyEvens(evenNumber: Int) throws -> Int {
	guard evenNumber % 2 == 0 else {
		throw NumberError.NotEven
	}

	guard evenNumber < 10 else {
		throw NumberError.TooLarge
	}

	return evenNumber * 2
}

The above, while slightly more cumbersome, this has well-defined benefits:

So, even though we've now modified our API to use swift exceptions, we can still retain the old Objective-C functionality giving the caller the choice of how they wish to handle the result of this failable operation.

NSError

In general, you should avoid NSError in Swift in favor of defining your own ErrorType. However, in the event you do need to use NSError (for interop with Objective-C, for instance):

Access Modifiers

Specify access modifiers only when they are needed and required by the compiler. For internal types and functions, do not explicitly specify the access modifier since all entities in Swift are internal by default.

final class Object {

    var myInt: Int

    private func doWork() {
        ...
    }

}

Further, the access modifier should always be presented first in the list before any other modifiers:

// Good!
private unowned var obj: Object

func doSomething() {
}

// Wrong!
weak public var obj: Object?

Imports

Import statements should be at the very top of the code file, and they should be listed in alphabetical order.

import AFNetworking
import Foundation
import ReactiveCocoa
import RealmSwift
import UIKit

The exception is for imports that are for testing only; they should be placed at the bottom of the list, in alphabetical order:

import AFNetworking
import UIKit
@testable import MyLibrary

Structs & Classes

In Swift, structs maintain value semantics which means their values are copied when assigned. Classes, on the other hand, act like pointers from C and Objective-C; they are called reference types and the internal data is shared amongst instances of assigning.

When composing your types, consider carefully what they're going to be used for before choosing what they should end up being. In general, consider structs for types that are:

Swift structs also have other, tangible benefits as well:

In general, you should favor structs and protocols over classes; even in cases where polymorphism would dictate the usage of a class, consider if you can achieve a similar result via protocols and extensions. This allows you to achieve polymorphism via composition rather than inheritance.

Nil Checking

Favor if-let checking over direct nil checking in all cases except when the result of this check is required:

guard let item = myItem else {
	return
}

doSomethingWith(item)

if let _ = error { // Prefer this over `if error != nil`
	fatalError()
}

func isError(error: Error?) -> Bool {
	return (error != nil) // In this case, we need the result of the bool, and this is much cleaner than the other options.
}

For style suggestions regarding nil checking visit our best practices section.

Implicit Getters

When overriding only the getter of a property, omit the use of get:

var myInt: Int {
	return 0
}

// Do not do this:
var myInt: Int {
	get {
		return 0
	}
}

For all other cases, specify the modifier as needed (set, didSet, etc.). This is compiler enforced.

Rationale The getter is implied enough to make sense without having to make it explicitly. It also cuts down on unnecessary verbiage and spacing to make code clearer.

Enums

For enum declarations, declare each enum case on a new line with its own case statement instead of a comma-separated list.

enum State {
	case open
	case closed
	case pending
	case faulted
}

Prefer singular case for enum names instead of plural: State vs. States:

var currentState = State.open
var previousState = States.closed // Reads less clearly than the previous option.

For enums with raw values, declare the raw value on the same line as its declaration:

enum HTTPMethod: String {
	case get = "GET"
	case post = "POST"
}

For any other functions or properties associated with the enum, place them after the last case item in the enum list:

enum State {
	case open
	case closed
	case pending
	case faulted

	func nextState() -> State {
		...
	}
}

In cases where the enum's type name can be omitted, do so:

let state = State.open

if state == .closed { ... // Prefer .closed instead of State.closed

Use of final

Classes should always be marked as final unless they are being used as a base class for another type. In instances where a class can be subclassed, any function or variable that should not be overridden by a subclass should be diligently marked as final.

// Not built for inheritance.
final class Object {

}

// Purposefully utilizable as a base class
class BaseClass {

	func doSomething () {
	}

	// Properly marked as final so subclasses cannot override
	final func update() {
	}

}

final class SubClass: BaseClass {

	override func doSomething() {
		update()
	}

}

Rationale Subclassing in instances where the original class was not built to support subclasses can be a common source of bugs. Marking classes as final indicates that it was developed under the assumption that it would act on its own without regard for subclasses.

Operators

Operator Overloading

Operator overloading is not recommended. Overloads often lead to ambiguous semantics, unintuitive behaviours and obscurities that are difficult for everyone to understand except the person who wrote them. Instead opt for less succinct, yet more descriptive function definitions throughout your code.

Custom Operators

Be wary of defining entirely new operators, unless your use case specifically requires it. In some situations borrowing an operator that is defined in the standard library of another language makes sense, such as operators specific to high level scientific or mathematical problem solving. The behaviour of your custom operator should be intuitive and obvious. Its semantics should not conflict with existing Swift operators.

When defining a custom operator, be clear and use exhaustive documentation. Provide an example use of the operator within your documentation that others will easily understand. Define the new operator in the same file as the type definition that is making use of it.

/// Defines a postfix operator used to
/// add 3 to the value of an integer.
postfix operator +++

/// Adds a value of 3 to an Integer 
/// by appending the postfix operator.
///
/// Eg. let result = 3+++
/// (result is now 6)
///
/// - Parameter n: integer to add 3 to
/// - Returns: the value of n plus 3
postfix func +++(n: Int) -> Int {
    return n + 3
}

Ensure there is always an existing function available that can be used as an alternative to the custom operator if required. Consumers of your type interface should be able to choose between using your custom operator as a shortcut, or using the function for further clarity.

Documentation

Well documented code is critical to help other developers understand what the code is doing. Every open, public and internal types should be documented. Additionally developers should annotate any private piece of code when its behavior is not trivial using the regular comment syntax //.

See our best practices about documenting the code.

Rationale A code without documentation is harder to understand, it is a good practice to document your code to help other developers understand the project, especially when it contains public APIs.