DigDes / swift-style-guide

Swift Style Guide

Содержание

• Форматирование
• Комментарии
• Соглашение об именовании
• Константы
• Именование графических ресурсов
• Структура файла
• Структура проекта

Форматирование

Пробелы и табуляция

• Используем 4 пробела вместо табуляции.
• Строки не должны содержать "замыкающиеся" пробелы.

Скобки

• Используем "единственный правильный скобочный стиль".
  Исключение: блоки кода, состоящие из одной строки (но, если строка содержит логику, то рекомендуется перенести её на новую строку).

Хорошо:

if user.isHappy {
    // ...
} else {
    // ...
}

Тоже хорошо:

guard let value = value else { return 0 }

defer { file.close() }

switch someEnum {
case .first: return 5
case .second: return 10
case .third: return 20
}

let squares = numbers.map { $0 * $0 }

var someProperty: Int {
    get { return otherObject.property }
    set { otherObject.property = newValue }
}

var someProperty: Int { return otherObject.somethingElse() }

required init?(coder aDecoder: NSCoder) { fatalError("no coder") }

Плохо:

if user.isHappy
{  
    // ...
}  
else {
    // ...
}

Плохо:

if let user = user { usernameLabel.text = user.firstName + user.middleName + user.lastName }

Ограничения по длине

• Длина строки ограничена 140 символами.
• Длина файла ограничена 500 строками.

Точка с запятой

• Символ ; в конце строки не используется без необходимости.

Хорошо:

func printSum(_ a: Int, _ b: Int) {
    let sum = a + b
    print(sum)
}

Плохо:

func printSum(_ a: Int, _ b: Int) {
    let sum = a + b;
    print(sum);
}

Горизонтальные отступы

• Зарезервированные слова (такие как if, guard, while, switch) отделяются от выражения, следующего за ними, одним пробелом.

Хорошо:

if (x == 0 && y == 0) || z == 0 {
    // ...
}

Плохо:

if(x == 0 && y == 0) || z == 0 {
    // ...
}

• Если фигурные скобки используются в одной строке с некоторым кодом, то они отделяются от него одним пробелом ({ отделяется с двух сторон, } отделяется только спереди).

Хорошо:

let nonNegativeCubes = numbers.map { $0 * $0 * $0 }.filter { $0 >= 0 }

Плохо:

let nonNegativeCubes = numbers.map { $0 * $0 * $0 } .filter { $0 >= 0 }
let nonNegativeCubes = numbers.map{$0 * $0 * $0}.filter{$0 >= 0}

• Бинарные и тернарные операторы отделяются пробелом с двух сторон. Исключение: операторы ..< и ....

Хорошо:

var x = 5

func sum(_ numbers: [Int], initialValue: Int = 0) {
    // ...
}

let substring = string[index..<string.endIndex]

Плохо:

var x=5

func sum(_ numbers: [Int], initialValue: Int=0) {
    // ...
}

let substring = string[index ..< string.endIndex]

• После символов , и : ставится пробел, но перед ними не ставится.

Хорошо:

let numbers = [1, 2, 3]

var nameAgeMap: [String: Int] = []

Плохо:

let numbers = [1,2,3]
let numbers = [1 ,2 ,3]
let numbers = [1 , 2 , 3]

var nameAgeMap: [String:Int] = []
var nameAgeMap: [String : Int] = []

• Использование горизонтального выравнивания в коде запрещено.

Хорошо:

struct DataPoint {
    var value: Int
    var primaryColor: UIColor
}

Плохо:

struct DataPoint {
    var value:        Int
    var primaryColor: UIColor
}

struct DataPoint {
    var primaryColor: UIColor
           var value: Int
}

Вертикальные отступы

• Одна пустая строка используется в следующих местах:
  • Между функциями и свойствами
  • При необходимости разделить код на логические части
  • В конце файла
• Использование двух пустых строк подряд не допускается.

Комментарии

• После // и /// используется 1 пробел.
• Если комментарий находится в одной строке с кодом, то он отделяется спереди двумя пробелами.

Хорошо:

let initialFactor = 2  // Комментарий.

Плохо:

let initialFactor = 2 //    Комментарий.

• Использование блочных комментариев (/* ... */) не допускается.

Документация

• Для документационных комментариев используем ///
• Использование Javadoc-комментариев (/** ... */) не допускается.

Хорошо:

/// Возвращает числовое значение заданной цифры, представленной в виде UnicodeScalar.
///
/// - Parameters:
///   - digit: Unicode-скаляр, числовое значение которого должно быть возвращено.
///   - radix: Основание между 2 и 36, используемое для вычисления числового значения.
/// - Returns: Числовое значение скаляра.
func numericValue(of digit: UnicodeScalar, radix: Int = 10) -> Int {
    // ...
}

Плохо:

/**
 * Возвращает числовое значение заданной цифры, представленной в виде UnicodeScalar.
 *
 * - Parameters:
 *   - digit: Unicode-скаляр, числовое значение которого должно быть возвращено.
 *   - radix: Основание между 2 и 36, используемое для вычисления числового значения.
 * - Returns: Числовое значение скаляра.
 */
func numericValue(of digit: UnicodeScalar, radix: Int = 10) -> Int {
    // ...
}

• Приветствуется использование специальной разметки для более информативного просмотра документации через Quick Help .
• Для автоматической генерации шаблона документации можно использовать сочетание ⌘ ⌥ /.

Соглашение об именовании

Константы

Именование графических ресурсов

Изображения должны быть названы в ВерблюжьемРегистре с описанием их назначения, содержать имя класса или свойства, для которого они предназначены (если такое имеется), далее идет цвет или расположение, и в конце состояние элемента, для которого предназначено изображение.

Хорошо

• RefreshBarButtonIcon / RefreshBarButtonIcon@2x and RefreshBarButtonIconSelected / RefreshBarButtonIconSelected@2x
• ArticleNavigationBarWhite / ArticleNavigationBarWhite@2x and ArticleNavigationBarBlackSelected / ArticleNavigationBarBlackSelected@2x.

Изображения, используемые для одинаковых целей должны быть сгруппированы в папки.

Важно: Перед добавлением изображения в ассет, переименуйте его. Если переименовать изображение после добавления, имя файла останется прежним.

Структура файла

Структура проекта