Skip to content

Latest commit

 

History

History
207 lines (176 loc) · 11.2 KB

styleguide.md

File metadata and controls

207 lines (176 loc) · 11.2 KB
Raw

Random-Pro стайлгайд для iOS

При написании кода следует руководствоваться гайдлайнами Apple и данным стайлгайдом. Ссылка на Swift API Design Guidelines

1. Нейминг

  • 1.1 Для кода используем английский язык и английские названия (не транслит, если это не аббревиатура).
  • 1.2 Документацию к коду и комментарии пишем на русском языке.
  • 1.3 Название файла = названию типа объявленному в этом файле. Если это расширение типа, то название пишем в формате "Type+Protocol".
  • 1.4 Использовать префиксы файлов нежелательно (возможно в редких условиях).
  • 1.5 Ясность в контексте использования (самодокументируемость). Объявление свойств и методов происходит в одном месте кода, а использование будет во многих частях кода, поэтому акцент в нейминге должен быть на читаемость в месте использования.
  • 1.6 Нейминг методов исходя из их сайд-эффектов в первую очередь, если они есть.

Хорошо:

func printFullName() {
  print("\(firstName) \(lastName)")
}

Плохо:

func fullName() {
  print("\(firstName) \(lastName)")
}
  • 1.7 Приоритетность ясности в отношении краткости (однозначность восприятия).

Хорошо:

presenter.showAlert()

Плохо:

presenter.show() // Из названия не ясно, что покажет презентер
  • 1.8 Префиксы функций/свойств не должны нести ложный характер.

Хорошо:

// func
serverService.getLists(with id: Type) // Загрузка списка
factory.makeCoordinator(with transport: Transportable) -> DigestCoordinatorOutput // Создаём координатор
// property
output.addressList // Получаем значение напрямую из свойства

Плохо:

// func
serverService.lists(with id: Type)
factory.getCoordinator(with transport: Transportable) -> DigestCoordinatorOutput // Под капотом происходит создание координатора, а не получение его извне
// property
output.getAddressList // Получаем значение напрямую из свойства, а не откуда-то извне
  • 1.9 Не использовать в нейминге названия паттернов, если сущность не является применением этого паттерна.
  • 1.10 Лучше использовать термины, которые не удивляют экспертов или путают начинающих. (напр. не называть паттерном то, что им не является).

Хорошо:

final class ElementsFactory {
  func makeElements() -> [Element] {
    var elements: [Element] = []
    ...
    return elements
  }
}

Плохо:

// Данный класс не соответсвует паттерну Builder и может ввести в заблуждение своим названием
final class ElementsBuilder {
  func build() -> [Element] {
    var elements: [Element] = []
    ...
    return elements
  }
}
  • 1.11 Нейминг объявления типов и протоколов в UpperCamelCase, всё остальное в lowerCamelCase.

Хорошо:

let user = User()
user.printFullName()

Плохо:

let User = user()
User.PrintFullName()
  • 1.12 По возможности избегать аббревиатур. Если использование аббревиатуры необходимо, то аббревиатуру писать заглавными буквами. Если название начинается с аббревиатуры, то пишем её маленькими буквами.

Хорошо:

let mainViewController: UIViewController
let id: String
let documentID: String

Плохо:

let mainVC: UIViewController
let ID: String
let documentId: String
  • 1.13 Нейминг исходя из роли, но не из типа переменной или свойства. Название типа можно добавлять, если это помогает лучшему пониманию.

Хорошо:

let personAge: Int
let cityPopulation: Int

Плохо:

let age: Int
let population: Int

2. Структура кода

  • 2.1 Группируйте похожий код и размещайте его вместе. Таким образом, код будет легче читать, понимать и поддерживать.
  • 2.2 Используйте пространства имен, чтобы создать четкую структуру и разделить код на логические блоки.
  • 2.3 Разделяйте код на мелкие функции, которые выполняют одну задачу. Это упростит чтение и улучшит переиспользование кода.
  • 2.4 Объявляйте переменные и константы ближе к месту их использования.

Хорошо:

func calculateArea() -> Double {
  let width = 10.0
  let height = 20.0
  return width * height
}

Плохо:

let width = 10.0
let height = 20.0

func calculateArea() -> Double {
  return width * height
}
  • 2.5 Избегайте дублирования кода. Если вы заметили, что один и тот же фрагмент кода используется в нескольких местах, рассмотрите возможность его выделения в отдельную функцию или компонент.

3. Комментарии и документация

  • 3.1 Пишите комментарии на русском языке для объяснения сложной логики или решения.
  • 3.2 Используйте комментарии для разделения кода на секции и описания основных частей программы.
  • 3.3 Не злоупотребляйте комментариями. Если код написан понятно и структурировано, то комментарии могут быть избыточными.
  • 3.4 Документируйте функции, классы и протоколы, когда это необходимо, используя стандартные форматы комментирования.

Пример:

/**
 Функция для конвертации температуры из градусов Цельсия в градусы Фаренгейта.

 - Parameter celsius: Температура в градусах Цельсия.
 - Returns: Температура в градусах Фаренгейта.
*/
func convertToFahrenheit(celsius: Double) -> Double {
  return (celsius * 9/5) + 32
}

4. Тестирование и отладка

  • 4.1 Используйте Unit-тесты для проверки корректности вашего кода. Это поможет избежать ошибок и упростит рефакторинг кода.
  • 4.2 Не стесняйтесь использовать отладчик (debugger) для нахождения ошибок и лучшего понимания того, как работает ваш код.
  • 4.3 Используйте логгирование для отслеживания происходящих событий в вашем приложении, но не забывайте удалять лишние логи перед релизом.
  • 4.4 При написании тестов, используйте названия функций, которые описывают, что именно вы тестируете. Это поможет при дальнейшем чтении и поддержке тестов.

Пример:

func testConvertToMilesValidKilometersReturnsMiles() {
  // Тестируем конвертацию километров в мили
}
  • 4.5 Используйте XCTAssert и другие проверки для сравнения ожидаемых результатов с реальными.

5. Использование сторонних библиотек

  • 5.1 При выборе сторонней библиотеки, оценивайте ее качество, активность разработки и совместимость с проектом.
  • 5.2 Используйте менеджеры зависимостей Swift Package Manager для упрощения подключения и обновления библиотек.
  • 5.3 Будьте осторожны при использовании библиотек с неразрешенными лицензиями или сомнительным происхождением.

6. Оптимизация и производительность

  • 6.1 Избегайте долгих и ресурсоемких операций в главном потоке, чтобы избежать "подтормаживания" интерфейса. Используйте GCD (Grand Central Dispatch) или OperationQueue для выполнения задач в фоновом потоке.
  • 6.2 По возможности используйте механизмы кеширования для уменьшения времени загрузки данных и снижения нагрузки на сеть.
  • 6.3 Используйте инструменты анализа производительности, такие как Instruments, для выявления и исправления проблем с производительностью.

7. Обработка ошибок и исключений

  • 7.1 Используйте механизмы обработки ошибок Swift, такие как try, catch и throw, чтобы обрабатывать ошибки в вашем коде.
  • 7.2 Не игнорируйте ошибки и исключения. Вместо этого обрабатывайте их корректно, выводите сообщения об ошибках и предоставляйте пользователю возможность исправить проблему или повторить операцию.

Пример обработки ошибок:

do {
  try performOperation()
} catch let error {
  print("Ошибка: \(error)")
  showAlert(with: "Произошла ошибка", message: error.localizedDescription)
}