Following this style guide should:
- Make it easier to read and begin understanding unfamiliar code.
- Make code easier to maintain.
- Reduce simple programmer errors.
- Reduce cognitive load while coding.
- Keep discussions on diffs focused on the code's logic rather than its style.
Note that brevity is not a primary goal. Code should be made more concise only if other good code qualities (such as readability, simplicity, and clarity) remain equal or are improved.
- This guide is in addition to the official Swift API Design Guidelines. These rules should not contradict that document.
- These rules should not fight Xcode's ^ + I indentation behavior.
- We strive to make every rule lintable:
- If a rule changes the format of the code, it needs to be able to be reformatted automatically (either using SwiftLint autocorrect or SwiftFormat).
- For rules that don't directly change the format of the code, we should have a lint rule that throws a warning.
- Exceptions to these rules should be rare and heavily justified.
- Xcode Formatting
- Naming
- Style
- Patterns
- File Organization
- Objective-C Interoperability
- Contributors
- Amendments
You can enable the following settings in Xcode by running this script, e.g. as part of a "Run Script" build phase.
-
(link) Each line should have a maximum column width of 100 characters.
-
(link) Use 2 spaces to indent lines.
-
(link) Trim trailing whitespace in all lines.
-
(link) Use PascalCase for type and protocol names, and lowerCamelCase for everything else.
protocol SpaceThing { // ... } class SpaceFleet: SpaceThing { enum Formation { // ... } class Spaceship { // ... } var ships: [Spaceship] = [] static let worldName: String = "Earth" func addShip(_ ship: Spaceship) { // ... } } let myFleet = SpaceFleet()
Exception: You may prefix a private property with an underscore if it is backing an identically-named property or method with a higher access level
There are specific scenarios where a backing a property or method could be easier to read than using a more descriptive name.
- Type erasure
public final class AnyRequester<ModelType>: Requester { public init<T: Requester>(_ requester: T) where T.ModelType == ModelType { _executeRequest = requester.executeRequest } @discardableResult public func executeRequest( _ request: URLRequest, onSuccess: @escaping (ModelType, Bool) -> Void, onFailure: @escaping (Error) -> Void) -> URLSessionCancellable { return _executeRequest(request, session, parser, onSuccess, onFailure) } private let _executeRequest: ( URLRequest, @escaping (ModelType, Bool) -> Void, @escaping (NSError) -> Void) -> URLSessionCancellable }
- Backing a less specific type with a more specific type
final class ExperiencesViewController: UIViewController { // We can't name this view since UIViewController has a view: UIView property. private lazy var _view = CustomView() loadView() { self.view = _view } }
-
(link) Name booleans like
isSpaceship
,hasSpacesuit
, etc. This makes it clear that they are booleans and not other types. -
(link) Acronyms in names (e.g.
URL
) should be all-caps except when it’s the start of a name that would otherwise be lowerCamelCase, in which case it should be uniformly lower-cased.// WRONG class UrlValidator { func isValidUrl(_ URL: URL) -> Bool { // ... } func isProfileUrl(_ URL: URL, for userId: String) -> Bool { // ... } } let URLValidator = UrlValidator() let isProfile = URLValidator.isProfileUrl(URLToTest, userId: IDOfUser) // RIGHT class URLValidator { func isValidURL(_ url: URL) -> Bool { // ... } func isProfileURL(_ url: URL, for userID: String) -> Bool { // ... } } let urlValidator = URLValidator() let isProfile = urlValidator.isProfileUrl(urlToTest, userID: idOfUser)
-
(link) Names should be written with their most general part first and their most specific part last. The meaning of "most general" depends on context, but should roughly mean "that which most helps you narrow down your search for the item you're looking for." Most importantly, be consistent with how you order the parts of your name.
// WRONG let rightTitleMargin: CGFloat let leftTitleMargin: CGFloat let bodyRightMargin: CGFloat let bodyLeftMargin: CGFloat // RIGHT let titleMarginRight: CGFloat let titleMarginLeft: CGFloat let bodyMarginRight: CGFloat let bodyMarginLeft: CGFloat
-
(link) Include a hint about type in a name if it would otherwise be ambiguous.
// WRONG let title: String let cancel: UIButton // RIGHT let titleText: String let cancelButton: UIButton
-
(link) Event-handling functions should be named like past-tense sentences. The subject can be omitted if it's not needed for clarity.
// WRONG class ExperiencesViewController { private func handleBookButtonTap() { // ... } private func modelChanged() { // ... } } // RIGHT class ExperiencesViewController { private func didTapBookButton() { // ... } private func modelDidChange() { // ... } }
-
(link) Avoid Objective-C-style acronym prefixes. This is no longer needed to avoid naming conflicts in Swift.
// WRONG class AIRAccount { // ... } // RIGHT class Account { // ... }
-
(link) Avoid
*Controller
in names of classes that aren't view controllers.
-
(link) Don't include types where they can be easily inferred.
// WRONG let host: Host = Host() // RIGHT let host = Host()
enum Direction { case left case right } func someDirection() -> Direction { // WRONG return Direction.left // RIGHT return .left }
-
(link) Don't use
self
unless it's necessary for disambiguation or required by the language.final class Listing { init(capacity: Int, allowsPets: Bool) { // WRONG self.capacity = capacity self.isFamilyFriendly = !allowsPets // `self.` not required here // RIGHT self.capacity = capacity isFamilyFriendly = !allowsPets } private let isFamilyFriendly: Bool private var capacity: Int private func increaseCapacity(by amount: Int) { // WRONG self.capacity += amount // RIGHT capacity += amount // WRONG self.save() // RIGHT save() } }
-
(link) Bind to
self
when upgrading from a weak reference.//WRONG class MyClass { func request(completion: () -> Void) { API.request() { [weak self] response in guard let strongSelf = self else { return } // Do work completion() } } } // RIGHT class MyClass { func request(completion: () -> Void) { API.request() { [weak self] response in guard let self = self else { return } // Do work completion() } } }
-
(link) Add a trailing comma on the last element of a multi-line array.
// WRONG let rowContent = [ listingUrgencyDatesRowContent(), listingUrgencyBookedRowContent(), listingUrgencyBookedShortRowContent() ] // RIGHT let rowContent = [ listingUrgencyDatesRowContent(), listingUrgencyBookedRowContent(), listingUrgencyBookedShortRowContent(), ]
-
(link) Name members of tuples for extra clarity. Rule of thumb: if you've got more than 3 fields, you should probably be using a struct.
// WRONG func whatever() -> (Int, Int) { return (4, 4) } let thing = whatever() print(thing.0) // RIGHT func whatever() -> (x: Int, y: Int) { return (x: 4, y: 4) } // THIS IS ALSO OKAY func whatever2() -> (x: Int, y: Int) { let x = 4 let y = 4 return (x, y) } let coord = whatever() coord.x coord.y
-
(link) Place the colon immediately after an identifier, followed by a space.
// WRONG var something : Double = 0 // RIGHT var something: Double = 0
// WRONG class MyClass : SuperClass { // ... } // RIGHT class MyClass: SuperClass { // ... }
// WRONG var dict = [KeyType:ValueType]() var dict = [KeyType : ValueType]() // RIGHT var dict = [KeyType: ValueType]()
-
(link) Place a space on either side of a return arrow for readability.
// WRONG func doSomething()->String { // ... } // RIGHT func doSomething() -> String { // ... }
// WRONG func doSomething(completion: ()->Void) { // ... } // RIGHT func doSomething(completion: () -> Void) { // ... }
-
(link) Omit unnecessary parentheses.
// WRONG if (userCount > 0) { ... } switch (someValue) { ... } let evens = userCounts.filter { (number) in number % 2 == 0 } let squares = userCounts.map() { $0 * $0 } // RIGHT if userCount > 0 { ... } switch someValue { ... } let evens = userCounts.filter { number in number % 2 == 0 } let squares = userCounts.map { $0 * $0 }
-
(link) Omit enum associated values from case statements when all arguments are unlabeled.
// WRONG if case .done(_) = result { ... } switch animal { case .dog(_, _, _): ... } // RIGHT if case .done = result { ... } switch animal { case .dog: ... }
-
(link) Place function/type attributes on the line above the declaration.
// WRONG @objc class Spaceship { @discardableResult func fly() -> Bool { } } // RIGHT @objc class Spaceship { @discardableResult func fly() -> Bool { } }
-
(link) Multi-line arrays should have each bracket on a separate line. Put the opening and closing brackets on separate lines from any of the elements of the array. Also add a trailing comma on the last element.
// WRONG let rowContent = [listingUrgencyDatesRowContent(), listingUrgencyBookedRowContent(), listingUrgencyBookedShortRowContent()] let rowContent = [ listingUrgencyDatesRowContent(), listingUrgencyBookedRowContent(), listingUrgencyBookedShortRowContent() ] // RIGHT let rowContent = [ listingUrgencyDatesRowContent(), listingUrgencyBookedRowContent(), listingUrgencyBookedShortRowContent(), ]
-
(link) Use constructors instead of Make() functions for NSRange and others.
// WRONG let range = NSMakeRange(10, 5) // RIGHT let range = NSRange(location: 10, length: 5)
-
(link) Omit
Void
return types from function definitions.// WRONG func doSomething() -> Void { ... } // RIGHT func doSomething() { ... }
-
(link) Separate long function declarations with line breaks before each argument label and before the return signature. Put the open curly brace on the next line so the first executable line doesn't look like it's another parameter.
class Universe { // WRONG func generateStars(at location: Point, count: Int, color: StarColor, withAverageDistance averageDistance: Float) -> String { // This is too long and will probably auto-wrap in a weird way } // WRONG func generateStars(at location: Point, count: Int, color: StarColor, withAverageDistance averageDistance: Float) -> String { // Xcode indents all the arguments } // WRONG func generateStars( at location: Point, count: Int, color: StarColor, withAverageDistance averageDistance: Float) -> String { populateUniverse() // this line blends in with the argument list } // WRONG func generateStars( at location: Point, count: Int, color: StarColor, withAverageDistance averageDistance: Float) throws -> String { populateUniverse() // this line blends in with the argument list } // RIGHT func generateStars( at location: Point, count: Int, color: StarColor, withAverageDistance averageDistance: Float) -> String { populateUniverse() } // RIGHT func generateStars( at location: Point, count: Int, color: StarColor, withAverageDistance averageDistance: Float) throws -> String { populateUniverse() } }
-
(link) Long function invocations should also break on each argument. Put the closing parenthesis on the last line of the invocation.
// WRONG universe.generateStars(at: location, count: 5, color: starColor, withAverageDistance: 4) // WRONG universe.generateStars(at: location, count: 5, color: starColor, withAverageDistance: 4) // WRONG universe.generateStars( at: location, count: 5, color: starColor, withAverageDistance: 4 ) // WRONG universe.generate(5, .stars, at: location) // RIGHT universe.generateStars( at: location, count: 5, color: starColor, withAverageDistance: 4) // RIGHT universe.generate( 5, .stars, at: location)
-
(link) Favor
Void
return types over()
in closure declarations. If you must specify aVoid
return type in a function declaration, useVoid
rather than()
to improve readability.// WRONG func method(completion: () -> ()) { ... } // RIGHT func method(completion: () -> Void) { ... }
-
(link) Name unused closure parameters as underscores (
_
).Naming unused closure parameters as underscores reduces the cognitive overhead required to read closures by making it obvious which parameters are used and which are unused.
// WRONG someAsyncThing() { argument1, argument2, argument3 in print(argument3) } // RIGHT someAsyncThing() { _, _, argument3 in print(argument3) }
-
(link) Single-line closures should have a space inside each brace.
// WRONG let evenSquares = numbers.filter {$0 % 2 == 0}.map { $0 * $0 } // RIGHT let evenSquares = numbers.filter { $0 % 2 == 0 }.map { $0 * $0 }
-
(link) Infix operators should have a single space on either side. Prefer parenthesis to visually group statements with many operators rather than varying widths of whitespace. This rule does not apply to range operators (e.g.
1...3
) and postfix or prefix operators (e.g.guest?
or-1
).// WRONG let capacity = 1+2 let capacity = currentCapacity ?? 0 let mask = (UIAccessibilityTraitButton|UIAccessibilityTraitSelected) let capacity=newCapacity let latitude = region.center.latitude - region.span.latitudeDelta/2.0 // RIGHT let capacity = 1 + 2 let capacity = currentCapacity ?? 0 let mask = (UIAccessibilityTraitButton | UIAccessibilityTraitSelected) let capacity = newCapacity let latitude = region.center.latitude - (region.span.latitudeDelta / 2.0)
-
(link) Prefer initializing properties at
init
time whenever possible, rather than using implicitly unwrapped optionals. A notable exception is UIViewController'sview
property.// WRONG class MyClass { init() { super.init() someValue = 5 } var someValue: Int! } // RIGHT class MyClass { init() { someValue = 0 super.init() } var someValue: Int }
-
(link) Avoid performing any meaningful or time-intensive work in
init()
. Avoid doing things like opening database connections, making network requests, reading large amounts of data from disk, etc. Create something like astart()
method if these things need to be done before an object is ready for use. -
(link) Extract complex property observers into methods. This reduces nestedness, separates side-effects from property declarations, and makes the usage of implicitly-passed parameters like
oldValue
explicit.// WRONG class TextField { var text: String? { didSet { guard oldValue != text else { return } // Do a bunch of text-related side-effects. } } } // RIGHT class TextField { var text: String? { didSet { textDidUpdate(from: oldValue) } } private func textDidUpdate(from oldValue: String?) { guard oldValue != text else { return } // Do a bunch of text-related side-effects. } }
-
(link) Extract complex callback blocks into methods. This limits the complexity introduced by weak-self in blocks and reduces nestedness. If you need to reference self in the method call, make use of
guard
to unwrap self for the duration of the callback.//WRONG class MyClass { func request(completion: () -> Void) { API.request() { [weak self] response in if let self = self { // Processing and side effects } completion() } } } // RIGHT class MyClass { func request(completion: () -> Void) { API.request() { [weak self] response in guard let self = self else { return } self.doSomething(with: self.property, response: response) completion() } } func doSomething(with nonOptionalParameter: SomeClass, response: SomeResponseClass) { // Processing and side effects } }
-
(link) Prefer using
guard
at the beginning of a scope. -
(link) Access control should be at the strictest level possible. Prefer
public
toopen
andprivate
tofileprivate
unless you need that behavior. -
(link) Avoid global functions whenever possible. Prefer methods within type definitions.
// WRONG func age(of person, bornAt timeInterval) -> Int { // ... } func jump(person: Person) { // ... } // RIGHT class Person { var bornAt: TimeInterval var age: Int { // ... } func jump() { // ... } }
-
(link) Prefer putting constants in the top level of a file if they are
private
. If they arepublic
orinternal
, define them as static properties, for namespacing purposes.private let privateValue = "secret" public class MyClass { public static let publicValue = "something" func doSomething() { print(privateValue) print(MyClass.publicValue) } }
-
(link) Use caseless
enum
s for organizingpublic
orinternal
constants and functions into namespaces. Avoid creating non-namespaced global constants and functions. Feel free to nest namespaces where it adds clarity. -
(link) Use Swift's automatic enum values unless they map to an external source. Add a comment explaining why explicit values are defined.
To minimize user error, improve readability, and write code faster, rely on Swift's automatic enum values. If the value maps to an external source (e.g. it's coming from a network request) or is persisted across binaries, however, define the values explicity, and document what these values are mapping to.
This ensures that if someone adds a new value in the middle, they won't accidentally break things.
// WRONG enum ErrorType: String { case error = "error" case warning = "warning" } enum UserType: String { case owner case manager case member } enum Planet: Int { case mercury = 0 case venus = 1 case earth = 2 case mars = 3 case jupiter = 4 case saturn = 5 case uranus = 6 case neptune = 7 } enum ErrorCode: Int { case notEnoughMemory case invalidResource case timeOut } // RIGHT enum ErrorType: String { case error case warning } /// These are written to a logging service. Explicit values ensure they're consistent across binaries. // swiftlint:disable redundant_string_enum_value enum UserType: String { case owner = "owner" case manager = "manager" case member = "member" } // swiftlint:enable redundant_string_enum_value enum Planet: Int { case mercury case venus case earth case mars case jupiter case saturn case uranus case neptune } /// These values come from the server, so we set them here explicitly to match those values. enum ErrorCode: Int { case notEnoughMemory = 0 case invalidResource = 1 case timeOut = 2 }
-
(link) Use optionals only when they have semantic meaning.
-
(link) Prefer immutable values whenever possible. Use
map
andcompactMap
instead of appending to a new collection. Usefilter
instead of removing elements from a mutable collection.Mutable variables increase complexity, so try to keep them in as narrow a scope as possible.
// WRONG var results = [SomeType]() for element in input { let result = transform(element) results.append(result) } // RIGHT let results = input.map { transform($0) }
// WRONG var results = [SomeType]() for element in input { if let result = transformThatReturnsAnOptional(element) { results.append(result) } } // RIGHT let results = input.compactMap { transformThatReturnsAnOptional($0) }
-
(link) Handle an unexpected but recoverable condition with an
assert
method combined with the appropriate logging in production. If the unexpected condition is not recoverable, prefer aprecondition
method orfatalError()
. This strikes a balance between crashing and providing insight into unexpected conditions in the wild. Only preferfatalError
over aprecondition
method when the failure message is dynamic, since aprecondition
method won't report the message in the crash report.func didSubmitText(_ text: String) { // It's unclear how this was called with an empty string; our custom text field shouldn't allow this. // This assert is useful for debugging but it's OK if we simply ignore this scenario in production. guard !text.isEmpty else { assertionFailure("Unexpected empty string") return } // ... } func transformedItem(atIndex index: Int, from items: [Item]) -> Item { precondition(index >= 0 && index < items.count) // It's impossible to continue executing if the precondition has failed. // ... } func makeImage(name: String) -> UIImage { guard let image = UIImage(named: name, in: nil, compatibleWith: nil) else { fatalError("Image named \(name) couldn't be loaded.") // We want the error message so we know the name of the missing image. } return image }
-
(link) Default type methods to
static
. -
(link) Default classes to
final
. -
(link) Never use the
default
case whenswitch
ing over an enum.Enumerating every case requires developers and reviewers have to consider the correctness of every switch statement when new cases are added.
// WRONG switch anEnum { case .a: // Do something default: // Do something else. } // RIGHT switch anEnum { case .a: // Do something case .b, .c: // Do something else. }
-
(link) Check for nil rather than using optional binding if you don't need to use the value.
-
(link) Omit the
return
keyword when not required by the language.// WRONG ["1", "2", "3"].compactMap { return Int($0) } var size: CGSize { return CGSize( width: 100.0, height: 100.0) } func makeInfoAlert(message: String) -> UIAlertController { return UIAlertController( title: "ℹ️ Info", message: message, preferredStyle: .alert) } // RIGHT ["1", "2", "3"].compactMap { Int($0) } var size: CGSize { CGSize( width: 100.0, height: 100.0) } func makeInfoAlert(message: String) -> UIAlertController { UIAlertController( title: "ℹ️ Info", message: message, preferredStyle: .alert) }
-
(link) Use
AnyObject
instead ofclass
in protocol definitions.SE-0156, which introduced support for using the
AnyObject
keyword as a protocol constraint, recommends preferringAnyObject
overclass
:This proposal merges the concepts of
class
andAnyObject
, which now have the same meaning: they represent an existential for classes. To get rid of the duplication, we suggest only keepingAnyObject
around. To reduce source-breakage to a minimum,class
could be redefined astypealias class = AnyObject
and give a deprecation warning on class for the first version of Swift this proposal is implemented in. Later,class
could be removed in a subsequent version of Swift.// WRONG protocol Foo: class {} // RIGHT protocol Foo: AnyObject {}
-
(link) Alphabetize module imports at the top of the file a single line below the last line of the header comments. Do not add additional line breaks between import statements.
A standard organization method helps engineers more quickly determine which modules a file depends on.
// WRONG // Copyright © 2018 Airbnb. All rights reserved. // import DLSPrimitives import Constellation import Epoxy import Foundation //RIGHT // Copyright © 2018 Airbnb. All rights reserved. // import Constellation import DLSPrimitives import Epoxy import Foundation
Exception:
@testable import
should be grouped after the regular import and separated by an empty line.// WRONG // Copyright © 2018 Airbnb. All rights reserved. // import DLSPrimitives @testable import Epoxy import Foundation import Nimble import Quick //RIGHT // Copyright © 2018 Airbnb. All rights reserved. // import DLSPrimitives import Foundation import Nimble import Quick @testable import Epoxy
-
(link) Limit empty vertical whitespace to one line. Favor the following formatting guidelines over whitespace of varying heights to divide files into logical groupings.
-
(link) Files should end in a newline.
-
(link) Prefer pure Swift classes over subclasses of NSObject. If your code needs to be used by some Objective-C code, wrap it to expose the desired functionality. Use
@objc
on individual methods and variables as necessary rather than exposing all API on a class to Objective-C via@objcMembers
.class PriceBreakdownViewController { private let acceptButton = UIButton() private func setUpAcceptButton() { acceptButton.addTarget( self, action: #selector(didTapAcceptButton), forControlEvents: .TouchUpInside) } @objc private func didTapAcceptButton() { // ... } }
We encourage you to fork this guide and change the rules to fit your team’s style guide. Below, you may list some amendments to the style guide. This allows you to periodically update your style guide without having to deal with merge conflicts.