- Общие принципы
- Именование
- Отступы
- Комментарии
- Вложенные типы
- Организация кода
- Объявления функций
- Замыкания
- Типы
- Управление памятью
- Управление доступом
- Циклы
- Golden path
- Точки с запятыми
- Скобки в if else
- Копирайт
- Необязательные параметры функций
Основано на https://github.com/raywenderlich/swift-style-guide
Хорошо написанный код облегчает чтение и понимание его вашими коллегами и вами же в будущем. Относитесь с уважением к тому, кто будет читать ваш код.
- Глобальные константы недопустимы, они всегда должны находиться внутри неймспейса.
- Warnings компилятора считаются ошибками и не допускаются. Исключение: TODO:, FIXME:
Следует придерживаться правил Swift.org — Api Design Guidelines
- Имена переменных должны описывать переменную семантически (смысл её передавать), переменные вида a или x не допускаются.
- Следует избегать сокращений (например, res), если они не общеприняты (например, url).
- При объявлении функции/переменной именовать её следует, спрашивая себя: а будет ли это название понятно при её вызове/использовании (где может не быть того контекста для понимания, который есть при их объявлении)?
- Ясность названия всегда имеет приоритет над краткостью.
- Используется camelCase, а не snake_case.
- Имена типов и протоколов начинаются с заглавной, всё остальное со строчной.
- Название должно описывать роль, назначение переменной/функции, а не её тип.
- Фабрики должны начинаться со слова make.
- Функции должны именоваться соответсвенно их побочному действию:
- Если метод мутирующий, то используется глагол: sequence.sort(), то есть метод меняет саму sequence в этом примере.
- Если метод не мутируюший, то используется причастие: sequence.sorted(), метод возвращает отсортированную послевадельность, но сама исходная sequence при этом не изменяется.
- Протоколы именуются в зависимости от того, что они описывают:
- Если это сущность, то используется существительное: Person.
- Если это спобность, то название должно заканчиваться на -able, -ible: Drinkable, Convertible.
- Параметры в функциях должны именоваться так, чтобы вместе с именем метода они читались как документация к методу.
- Следует именовать параметры кортежей (tuples), потому что потом при ис
Как надо
struct WidgetContainer {
private let maximumWidgetCount = 100
var widgetButton: UIButton
var widgetHeightPercentage = 0.85
}
Как не надо
let MAX_WIDGET_COUNT = 100
struct widget_container {
var widgetBtn: UIButton
var widgetHeightPerc = 0.85
}
- Для идентации используется 4 пробела (не табы).
- У функций, циклов и других выражений (if, else, switch, while, etc.) открывающая фигурная скобка должна находиться на той же строке, что и выражение. Закрывающая же всегда на новой строке.
- Между конструкцией и открывающей фигурной скобкой должен быть ровно один пробел.
- Скобки вызова функции не отделяются от него пробелом.
- Между функциями должна быть ровно одна пустая строка, для удобства чтения и организации кода. Внутри функции допускаются пробелы для разделения блоков функциональности, но слишком много блоков указывает на то, что метод должен быть разделён на несколько (SRP).
Как надо
func doSomething() {
// Do something
}
if user.isHappy {
doSomething()
} else {
// Do something else
}
Как не надо
func doSomething (){
// Do something
}
if user.isHappy
{
doSomething ()
}
else{
// Do something else }
- Двоеточие всегда ставится без пробела слева и с одним пробелом справа. Исключения — тернарный оператор ? :, пустой словарь [:] и #selector синтаксис для параметров без имени (_:).
Комментарии должны описывать не то, что делает какой-то кусок кода, а то, _почему _он это делает.
Комментарии надо либо всё время поддерживать в актуальном состоянии, либо удалять.
Не надо писать посреди кода большие блочные комментарии на несколько строк, если это не документация.
Пример хорошего объявления класса:
class Circle: Shape {
var x: Int, y: Int
var radius: Double
var diameter: Double {
get {
return 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 {
return Double.pi * radius * radius
}
}
extension Circle: CustomStringConvertible {
var description: String {
return "center = \(centerString) area = \(area())"
}
private var centerString: String {
return "(\(x),\(y))"
}
}
Этот пример демонстрирует следующие правила:
— перед двоеточием пробел не ставится, а после — ставится (например, x: Int и circle: Shape)
— близкие по назначению переменные объявляются на одной строке
— блоки get, set, willSet и didSet должны быть сдвинуты вправо относительно родительского свойства
— модификаторы не указываются, если по умолчанию они и так включены (например, по умолчанию все свойства и методы — internal)
— модификаторы не указываются, когда мы переопределяем метод или свойство (например, override func area() → Double)
— дополнительные функции выносятся в расширения к классу
— в расширении к классу внутренние детали реализации (например, centerString) скрываются от внешнего мира с помощью модификатора private
Использование self
В отличие от Objective-C, в Свифте не обязательно использовать self при вызове методов или свойств объекта.
self обязателен только в некоторых случаях. Например, внутри замыканий, помеченных как @escaping, и в конструкторе — для того, чтобы отличить свойства объекта от аргументов конструктора.
Везде, где программа компилируется без self, self надо убирать.
Вычисляемые свойства
Если у вычисляемого свойства есть только геттер, то конструкцию get { ... } писать не надо.
Правильно:
var diameter: Double {
return radius * 2
}
Неправильно:
var diameter: Double {
get {
return radius * 2
}
}
Final
В экспериментальном коде помечать классы или свойства как final не обязательно — это отвлекает от сути. Но иногда final полезен — он помогает прояснить ваши намерения. В нижеприведённом коде класс Box имеет вполне определённое назначение, и его логично закрыть от наследования:
// Turn any generic type into a reference type using this Box class.
final class Box<T> {
let value: T
init(_ value: T) {
self.value = value
}
}
Рекомендацями этого раздела следует пользоваться только следующих ситуациях:
-
вы пишите код приложения, который не будет использован как cocoapod
-
вы пишите код с областью видимости
fileprivate
При необходимости использования вложенных типов (nested types
) подтипы необходимо складывать в extension
внури файла с основной моделью после ее описания. Колличество extension
в которые будут складываться вложенные типы выбираются по усмотрению разработчика. Если появилась необоходимость сделать вложенный тип, для вложенного типа, то его нахождение делается так-же на усмотрение разработчика. Каждый вложенный тип необходимо выделять MARK:
.
В случае, если колличество строк внутри файла превышает установленные ограничения, то допустимо разбивать типы по файлам по установленным выше правилам.
Правильно:
struct Person {
let id: String
let document: Document
let gender: Gender
}
// MARK: - Document
extension Person {
struct Document {
let id: String
let kind: Kind
// MARK: - Kind
enum Kind {
case plain
case notPlain
}
}
}
// MARK: - Gender
extension Person {
enum Gender {
case male
case female
case unspecified
}
}
Неправильно:
struct Person {
// MARK: - Document
struct Document {
enum Kind {
case plain
case notPlain
}
let id: String
let kind: Kind
}
// MARK: - Gender
enum Gender {
case male
case female
case unspecified
}
let id: String
let document: Document
let gender: Gender
}
При появлении нескольких типов с общим префиксом, из-за того, что они относятся к одному модулю (части функциональности), следует объявлять эти типы как вложенные используя общий тип, как неймпспейс.
Правильно:
class ConfirmOrderConfirmationCell: UITableViewCell {
let paymentInfoImageView = PaymentInfoImageView()
}
// MARK: - PaymentInfoImageView
extension ConfirmOrderConfirmationCell {
class PaymentInfoImageView: UIView { }
}
Неправильно:
class ConfirmOrderConfirmationPaymentInfoImageView: UIView { }
class ConfirmOrderConfirmationCell: UITableViewCell {
let paymentInfoImageView = ConfirmOrderConfirmationPaymentInfoImageView()
}
Используйте extensions для организации кода в логические блоки функциональности. Каждый extension следует помечать // MARK: -
для придания большей читаемости кода.
Следующая последовательность является рекомендацией для следования:
// MARK: - IBOutlet
// MARK: - Visual Components
// MARK: - Public Properties
// MARK: - Private Properties
// MARK: - Initializers
// MARK: - UIViewController(*)
// MARK: - Public methods
// MARK: - IBAction
// MARK: - Private Methods
// MARK: - Types
// MARK: - Constants
(*) Вместо вы должны написать другой
superclass
, методы которовы вы переопределяете.Внутри скоупа
MARK:
следует писать без-
, для того, чтобы не было разделителей внутри.
Вышепредствленная структура является исключительно рекомендацией, но при необходимости использовать схожее разделениеVisual Components
илиInitializers
лучше придерживаться предложенного нейминга.
Когда класс конформит несколько протоколов их необходимов разбивать в разные extensions. Такой подход поможет сгруппировать родственные методы вместе с протоколом, который они конформят. Протокол так-же необходимо обозначить // MARK: -
.
Правильно:
class MyViewController: UIViewController {
// class stuff here
}
// MARK: - UITableViewDataSource
extension MyViewController: UITableViewDataSource {
// table view data source methods
}
// MARK: - UIScrollViewDelegate
extension MyViewController: UIScrollViewDelegate {
// scroll view delegate methods
}
Неправильно:
class MyViewController: UIViewController, UITableViewDataSource, UIScrollViewDelegate {
// all methods
}
Короткие объявления функций надо писать в одну строчку. Открывающая фигурная скобка не должна переносится на новую строку:
func reticulateSplines(spline: [Double]) -> Bool {
// reticulate code goes here
}
Если у функции очень длинная сигнатура, то объявление функции надо разбивать на несколько строк. При этом все строки, кроме первой, должны быть с отступом:
func reticulateSplines(spline: [Double], adjustmentFactor: Double,
translateConstant: Int, comment: String) -> Bool {
// reticulate code goes here
}
Специальный синтаксис для замыканий надо использовать в единственном случае: среди параметров есть только одно замыкание и оно идёт последним.
Параметрам замыканий надо давать понятные имена.
Правильно:
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()
})
Неправильно:
UIView.animate(withDuration: 1.0, animations: { // не использован специальный синтаксис для последнего замыкания
self.myView.alpha = 0
})
UIView.animate(withDuration: 1.0, animations: {
self.myView.alpha = 0
}) { f in // здесь, наоборот, специальный синтаксис для замыкания использовать не надо; кроме того, f — непонятное название
self.myView.removeFromSuperview()
}
Если замыкание состоит из одного выражения, можно использовать неявный return:
attendeeList.sort { a, b in
a > b
}
Цепочки из методов высшего порядка ( strings.map { ...} filter {...} ) должны быть понятными и читаться однозначно.
Как расставлять пробелы и переносы строк в таких цепочках и следует ли использовать анонимные параметры ($0, $1 и так далее) — всё это остаётся на усмотрение автора.
Примеры того, как можно делать:
let value = numbers.map { $0 * 2 }.filter { $0 % 3 == 0 }.index(of: 90)
let value = numbers
.map {$0 * 2}
.filter {$0 > 50}
.map {$0 + 10}
Если есть возможность, надо использовать родные свифтовые типы (Double, String, Date), а не старые типы из Objective-C (NSNumber, NSString, NSDate).
В Свифте есть трансформации, которые превращают свифтовые типы в старые типы из Objective-C. Поэтому, когда понадобится какой-нибудь старый тип, его всегда можно получить из свифтового.
Правильно:
let width = 120.0 // Double
let widthString = (width as NSNumber).stringValue // String
Неправильно:
let width: NSNumber = 120.0 // NSNumber
let widthString: NSString = width.stringValue // NSString
Но при работе со SpriteKit можно использовать CGFloat, чтобы не было слишком много конверсий.
Константы
Константы определяются с помощью ключевого слова let, а переменные — с помощью ключевого слова var.
Если значение переменной не будет меняться, надо использовать let, а не var.
Совет: можно всегда использовать let и заменять его на var только тогда, когда компилятор начинает ругаться.
Константы можно объявить не только у объекта, но и у типа (static let ...).
Статические константы — лучше, чем глобальные переменные, потому что их легче отличить от полей класса.
Правильно:
enum Math {
static let e = 2.718281828459045235360287
static let root2 = 1.41421356237309504880168872
}
let hypotenuse = side * Math.root2 // сразу ясно, что root2 — статическая переменная в енуме Math
Неправильно:
e = 2.718281828459045235360287 // pollutes global namespace
let root2 = 1.41421356237309504880168872
let hypotenuse = side * root2 // не ясно, что такое root2: то ли локальная переменная, то ли глобальная
Статические методы и свойства работают примерно так же, как глобальные функции и переменные. Их не надо использовать слишком часто. Они полезны, когда нужно выделить функционал, относящийся к конкретному типу, или когда нужна совместимость с Objective-C.
Опциональные поля
Если переменная может стать равной nil, надо помечать такую переменную как опциональную с помощью знака ?
Если функция может вернуть nil, надо помечать возвращаемое значение функции как опциональное (тоже с помощью знака ?).
Implicitly-unwrapped переменные (var x: String!) надо использовать только тогда, когда точно известно, что они будут инициализированы перед первым использованием. Например, это могут быть дочерние вью, которые инициализируются во viewDidLoad().
Если мы обращаемся к опциональной переменной только один раз (или если надо обратиться к цепочке из вложенных опциональных полей), лучше воспользоваться знаком вопроса:
self.textContainer?.textField?.setNeedsDisplay()
Если мы обращаемся к опциональной переменной несколько раз подряд, то удобнее использовать if let ... :
if let textField = self.textContainer.textField {
textField.hidden = false
textField.backgroundColor = UIColor.green
textField.text = "This is green text field."
}
В названиях опциональных полей не надо подчёркивать их опциональность. Опциональность уже указана в типе.
Неправильно:
var optionalTitleString: String?
var maybeMainSubview: UIView?
Правильно:
var titleString: String?
var mainSubview: UIView?
Ленивая инициализация
Если нужно точно контролировать время создания объектов, надо использовать ленивую инициализацию. Это особенно актуально для вью-контроллеров, которые лениво загружают вью.
Для ленивой инициализации можно использовать либо замыкание, которое вызывается немедленно ( makeView { ... } () ), либо приватный фабричный метод.
Замыкание, которое вызывается немедленно:
lazy var locationManager: CLLocationManager = {
let manager = CLLocationManager()
manager.desiredAccuracy = kCLLocationAccuracyBest
manager.delegate = self
manager.requestAlwaysAuthorization()
return manager
} ()
Приватный фабричный метод:
lazy var locationManager: CLLocationManager = self.makeLocationManager()
private func makeLocationManager() -> CLLocationManager {
let manager = CLLocationManager()
manager.desiredAccuracy = kCLLocationAccuracyBest
manager.delegate = self
manager.requestAlwaysAuthorization()
return manager
}
Примечания:
— здесь точно не будет ретэйн-цикла, поэтому не обязательно использовать [unowned self]
— у этого метода есть побочный эффект: когда мы вызываем manager.requestAlwaysAuthorization(), на экране телефона может появиться алерт, спрашивающий у пользователя разрешения; именно поэтому имеет смысл использовать ленивую инициализацию
Автоматический вывод типов
Обычно при объявлении переменных не надо указывать их тип — компилятор догадается и сам, а код станет проще.
Случаи, когда тип переменных всё-таки надо указывать:
— сложные массивы или другие коллекции
— переменные типа CGFloat или Int16
Правильно:
let message = "Click the button"
let currentBounds = computeViewBounds()
var names = ["Mic", "Sam", "Christine"]
let maximumWidth: CGFloat = 106.5
Неправильно:
let message: String = "Click the button"
let currentBounds: CGRect = computeViewBounds()
let names = [String]()
Пустые массивы и словари лучше объявлять так:
var names: [String] = []
var lookup: [String: Int] = [:]
А так лучше не делать:
var names = [String]()
var lookup = [String: Int]()
Примечание: если мы пользуемся описанным стилем объявления переменных, то хорошие и понятные названия переменных играют ещё бо́льшую роль.
Сокращённый синтаксис для контейнеров
Надо использовать сокращённые варианты для объявления словарей, массивов и опциональных полей.
Правильно:
var deviceModels: [String]
var employees: [Int: String]
var faxNumber: Int?
Неправильно:
var deviceModels: Array<String>
var employees: Dictionary<Int, String>
var faxNumber: Optional<Int>
В коде не должно быть ретэйн-циклов. Даже если это не боевой код, а какие-то эксперименты.
Чтобы избавиться от ретэйн-циклов, надо:
— использовать поля типа weak и unowned
— использовать структуры и енумы вместо классов
Увеличение времени жизни объекта
Иногда нужно, чтобы объект был жив внутри замыкания, даже если все остальные ссылки на него удалены.
Чтобы продлить время жизни объекта, можно использовать связку: сначала говорим [weak self]
, а после этого — guard let _self = self else { return }
:
resource.request().onComplete { [weak self] response in
guard let _self = self else {
return
}
let model = _self.updateModel(response)
self.updateUI(model)
}
Если сразу известно, что объект будет жить дольше, чем замыкание, то в замыкании надо использовать [unowned self]
.
Если не очевидно, кто будет жить дольше, то лучше использовать [weak self]
.
Кроме связки [weak self]
+ guard let _self = self else { return }
, есть два других способа обращаться с объектом внутри замыкания, но они плохие.
Вот так делать не надо:
resource.request().onComplete { [unowned self] response in
let model = self.updateModel(response)
self.updateUI(model)
}
Объект self может быть удалён из памяти перед вызовом замыкания; в этом случае метод self.updateModel() упадёт.
Вот так делать тоже не надо:
resource.request().onComplete { [weak self] response in
let model = self?.updateModel(response)
self?.updateUI(model)
}
В промежутке между .updateModel() и .updateUI() объект self может быть удалён из памяти. Получится, что self?.updateModel() сработает, а self?.updateUI() — нет.
Модификатор управления доступом (private, fileprivate или public) должен стоять первым среди всех остальных модификаторов. Единственное, что может стоять перед ним — модификатор static и атрибуты (например, @IBAction или @IBOutlet).
Правильно:
class TimeMachine {
private dynamic lazy var fluxCapacitor = FluxCapacitor()
}
Неправильно:
class TimeMachine {
lazy dynamic private var fluxCapacitor = FluxCapacitor()
}
Лучше использовать конструкцию for-in, а не while.
Правильно:
for _ in 0..<3 {
print("Hello three times")
}
for (index, person) in attendeeList.enumerated() {
print("\(person) is at position #\(index)")
}
for index in stride(from: 0, to: items.count, by: 2) {
print(index)
}
for index in (0...3).reversed() {
print(index)
}
Неправильно:
var i = 0
while i < 3 {
print("Hello three times")
i += 1
}
var i = 0
while i < attendeeList.count {
let person = attendeeList[i]
print("\(person) is at position #\(i)")
i += 1
}
Не надо плодить вложенные if. Там, где возможно, надо заменять их на конструкцию guard let x = ... else ...
Неправильно:
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
}
}
Правильно:
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
}
Если мы разворачиваем сразу несколько опшионалов, то лучше делать это одной командой:
guard let number1 = number1,
let number2 = number2,
let number3 = number3 else {
fatalError("impossible")
}
// do something with numbers
Вот так — плохо:
if let number1 = number1 {
if let number2 = number2 {
if let number3 = number3 {
// do something with numbers
} else {
fatalError("impossible")
}
} else {
fatalError("impossible")
}
} else {
fatalError("impossible")
}
Failing guards
В конструкции guard let x = ... else ... блок else ... должен быть устроен просто.
В идеале он должен состоять из единственной команды (return, throw, break, continue или fatalError()).
Если в нескольких гардах требуется выполнить один и тот же код, который что-то чистит, то этот код лучше обернуть в конструкцию defer ... , чтобы избежать дублирования.
В Свифте не обязательно ставить точку с запятой в конце строки. Точка с запятой нужна только тогда, когда вы объединяете на одной строке несколько выражений.
Но так делать не надо, лучше, чтобы каждое выражение было на своей строке.
Единственное место, где можно использовать точку с запятой — циклы for-conditional-increment.
Но вместо них лучше использовать циклы for-in.
Вокруг условий в if ... else ... скобки не нужны.
Правильно:
if string.isEmpty {
print("String is empty.")
}
Неправильно:
if (string.isEmpty) {
print("String is empty.")
}
В начале каждого нового файла должна стоять шапка с копирайтом:
//
// Copyright © 2018 Tutu.ru. All rights reserved.
//
Для функций и методов класса/структуры и т.п.
- необязательные параметры должны быть в конце списка аргументов
- необязательные параметры должны иметь значение по умолчанию (если требуется)
func foo(bar: Int, baz: Int? = nil) {
}
Для методов протокола
- необязательные параметры должны быть в конце списка аргументов
- в экстеншене к протоколу реализованы методы без опциональных параметров (если требуется)
protocol Faz {
func foo(bar: Int, baz: Int?)
}
extension Faz {
func foo(bar: Int) {
foo(bar: bar, baz: nil)
}
}