Rakuyo Swift 风格指南

本风格指南衍生自 Airbnb，经过修改和扩展，并将命名空间重命名为 Rakuyo。

目标

遵循本风格指南应能：

更容易阅读和理解不熟悉的代码。
使代码更容易维护。
减少简单的程序员错误。
降低编码时的认知负荷。
使关于差异的讨论集中在代码的逻辑上，而不是其风格上。

请注意，简洁不是主要目标。只有在其他良好的代码质量（如可读性、简洁性和清晰度）保持不变或得到改进时，才应使代码更简洁。

指导原则

本指南是对官方 Swift API 设计指南的补充。这些规则不应与该文档冲突。
这些规则不应与 Xcode 的 ^ + I 缩进行为冲突。
我们努力使每条规则都可进行lint检查
- 如果一条规则改变了代码的格式，它需要能够自动重新格式化（可以使用 SwiftFormat 或 SwiftLint 自动更正）。
- 对于不直接改变代码格式的规则，我们应该有一个 lint 规则，该规则抛出警告或错误。
- 这些规则的例外情况应该很少见，并且需要充分的理由。

asdf/mise 插件

RakuyoKit/asdf-swift-style-guide 是一个 asdf 插件 (它也支持 mise)。

您可以通过此插件下载 lint、格式化和其他配置文件，然后以您喜欢的方式自由执行相关命令。

Swift Package Manager 命令插件

此存储库包含一个 Swift Package Manager 命令插件，您可以使用它来根据风格指南自动重新格式化或 lint 您的包。要将此命令插件与您的包一起使用，您只需将此存储库添加为依赖项

dependencies: [
  .package(url: "https://github.com/RakuyoKit/swift", from: "1.4.0"),
]

然后在您的包目录中运行 format 命令插件

$ swift package format

用法指南

# Supported in Xcode 14+. Prompts for permission to write to the package directory.
$ swift package format

# When using the Xcode 13 toolchain, or a noninteractive shell, you must use:
$ swift package --allow-writing-to-package-directory format

# To just lint without reformatting, you can use `--lint`:
$ swift package format --lint

# By default the command plugin runs on the entire package directory.
# You can exclude directories using `exclude`:
$ swift package format --exclude Tests

# Alternatively you can explicitly list the set of paths and/or SPM targets:
$ swift package format --paths Sources Tests Package.swift
$ swift package format --targets RakuyoSwiftFormatTool

# The plugin infers your package's minimum Swift version from the `swift-tools-version`
# in your `Package.swift`, but you can provide a custom value with `--swift-version`:
$ swift package format --swift-version 5.3

如果存在需要注意的 lint 失败，则包插件返回非零退出代码。

在 --lint 模式下，来自任何工具的任何 lint 失败都将导致非零退出代码。
在没有 --lint 的标准自动更正模式下，只有来自 SwiftLint 仅 lint 规则的失败才会导致非零退出代码。

Xcode 格式化

您可以通过运行此脚本，例如作为“运行脚本”构建阶段的一部分，在 Xcode 中启用以下设置。

(链接) 每行应具有最大 100 个字符的列宽。

为什么？

由于更大的屏幕尺寸，我们选择了一个大于 80 的页面引导。

我们目前仅“严格执行”（lint / 自动格式化）最大 130 个字符的列宽，以限制需要手动清理略高于阈值的重新格式化行的情况。
(链接) 使用 4 个空格来缩进代码行。
(链接) 删除所有行中的尾随空格。

⬆ 返回顶部

命名

(链接) 类型和协议名称使用 PascalCase，其他所有内容使用 lowerCamelCase。

protocol SpaceThing {
  // ...
}

class SpaceFleet: SpaceThing {

  enum Formation {
    // ...
  }

  class Spaceship {
    // ...
  }

  var ships: [Spaceship] = []
  static let worldName: String = "Earth"

  func addShip(_ ship: Spaceship) {
    // ...
  }
}

let myFleet = SpaceFleet()

例外：如果私有属性支持具有更高访问级别的同名属性或方法，则可以使用下划线作为前缀。

为什么？

在某些特定情况下，以下划线为前缀的支持属性或方法可能比使用更具描述性的名称更容易阅读。

类型擦除

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, onSuccess, onFailure)
  }

  private let _executeRequest: (
    URLRequest,
    @escaping (ModelType, Bool) -> Void,
    @escaping (Error) -> Void)
    -> URLSessionCancellable
}

使用更具体的类型支持不太具体的类型

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
  }
}

(链接) 将布尔值命名为 isSpaceship、hasSpacesuit 等。 这可以清楚地表明它们是布尔值，而不是其他类型。

(链接) 名称中的首字母缩略词（例如 URL）应全部大写，除非它是名称的开头，否则将为 lowerCamelCase，在这种情况下，应统一小写。

// 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)

(链接) 名称的写法应该是最概括的部分在前，最具体的部分在后。 “最概括”的含义取决于上下文，但大致应表示“最有助于您缩小搜索范围以查找所需项目的内容”。最重要的是，保持名称各个部分顺序的一致性。
```
// 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
```

(链接) 如果在名称中包含类型提示，否则会产生歧义。

// WRONG
let title: String
let cancel: UIButton

// RIGHT
let titleText: String
let cancelButton: UIButton

(链接) 事件处理函数应命名为过去时句子。 如果不需要为了清晰起见，可以省略主语。

// WRONG
class ExperiencesViewController {

  private func handleBookButtonTap() {
    // ...
  }

  private func modelChanged() {
    // ...
  }
}

// RIGHT
class ExperiencesViewController {

  private func didTapBookButton() {
    // ...
  }

  private func modelDidChange() {
    // ...
  }
}

(链接) 避免使用 Objective-C 风格的首字母缩写词前缀。 这在 Swift 中不再需要避免命名冲突。
```
// WRONG
class AIRAccount {
  // ...
}

// RIGHT
class Account {
  // ...
}
```
(链接) 在非视图控制器的类名中避免使用 *Controller。

为什么？

Controller 是一个重载的后缀，不提供有关类职责的信息。

⬆ 返回顶部

风格

(链接) 不要包含可以轻松推断的类型。

// WRONG
let sun: Star = Star(mass: 1.989e30)
let earth: Planet = Planet.earth

// RIGHT
let sun = Star(mass: 1.989e30)
let earth = Planet.earth

// NOT RECOMMENDED. However, since the linter doesn't have full type information, this is not enforced automatically.
let moon: Moon = earth.moon // returns `Moon`

// RIGHT
let moon = earth.moon
let moon: PlanetaryBody? = earth.moon

// WRONG: Most literals provide a default type that can be inferred.
let enableGravity: Bool = true
let numberOfPlanets: Int = 8
let sunMass: Double = 1.989e30

// RIGHT
let enableGravity = true
let numberOfPlanets = 8
let sunMass = 1.989e30

// WRONG: Types can be inferred from if/switch expressions as well if each branch has the same explicit type.
let smallestPlanet: Planet =
  if treatPlutoAsPlanet {
    Planet.pluto
  } else {
    Planet.mercury
  }

// RIGHT
let smallestPlanet =
  if treatPlutoAsPlanet {
    Planet.pluto
  } else {
    Planet.mercury
  }

(链接) 首选让变量或属性的类型从右侧值推断出来，而不是在左侧显式写入类型。

当右侧值为带有前导点的静态成员（例如 init、static 属性/函数或枚举 case）时，首选使用推断类型。这适用于局部变量和属性声明

// WRONG
struct SolarSystemBuilder {
  let sun: Star = .init(mass: 1.989e30)
  let earth: Planet = .earth

  func setUp() {
    let galaxy: Galaxy = .andromeda
    let system: SolarSystem = .init(sun, earth)
    galaxy.add(system)
  }
}

// RIGHT
struct SolarSystemBuilder {
  let sun = Star(mass: 1.989e30)
  let earth = Planet.earth

  func setUp() {
    let galaxy = Galaxy.andromeda
    let system = SolarSystem(sun, earth)
    galaxy.add(system)
  }
}

在其他情况下仍然允许显式类型

// RIGHT: There is no right-hand-side value, so an explicit type is required.
let sun: Star

// RIGHT: The right-hand-side is not a static member of the left-hand type.
let moon: PlantaryBody = earth.moon
let sunMass: Float = 1.989e30
let planets: [Planet] = []
let venusMoon: Moon? = nil

在极少数情况下，推断类型语法与显式类型语法具有不同的含义。在这些情况下，仍然允许显式类型语法

extension String {
  static let earth = "Earth"
}

// WRONG: fails with "error: type 'String?' has no member 'earth'"
let planetName = String?.earth

// RIGHT
let planetName: String? = .earth

struct SaturnOutline: ShapeStyle { ... }

extension ShapeStyle where Self == SaturnOutline {
  static var saturnOutline: SaturnOutline { 
    SaturnOutline() 
  }
}

// WRONG: fails with "error: static member 'saturnOutline' cannot be used on protocol metatype '(any ShapeStyle).Type'"
let myShape2 = (any ShapeStyle).myShape

// RIGHT: If the property's type is an existential / protocol type, moving the type
// to the right-hand side will result in invalid code if the value is defined in an
// extension like `extension ShapeStyle where Self == SaturnOutline`.
// SwiftFormat autocorrect detects this case by checking for the existential `any` keyword.
let myShape1: any ShapeStyle = .saturnOutline

(链接) 除非需要消除歧义或语言要求，否则不要使用 self。

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()
  }
}

(链接) 从弱引用升级时绑定到 self。

// 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 else { return }
      // Do work
      completion()
    }
  }
}

(链接) 在多行数组的最后一个元素上添加尾随逗号。

// WRONG
let rowContent = [
  listingUrgencyDatesRowContent(),
  listingUrgencyBookedRowContent(),
  listingUrgencyBookedShortRowContent()
]

// RIGHT
let rowContent = [
  listingUrgencyDatesRowContent(),
  listingUrgencyBookedRowContent(),
  listingUrgencyBookedShortRowContent(),
]

(链接) 集合文字的括号内不应有空格。

// WRONG
let innerPlanets = [ mercury, venus, earth, mars ]
let largestObjects = [ .star: sun, .planet: jupiter  ]

// RIGHT
let innerPlanets = [mercury, venus, earth, mars]
let largestObjects = [.star: sun, .planet: jupiter]

(链接) 命名元组的成员以获得额外的清晰度。 经验法则：如果您有超过 3 个字段，您可能应该使用结构体。

// 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

(链接) 冒号后面应始终跟一个空格，但前面不应有空格。

// WRONG
let planet:CelestialObject = sun.planets[0]
let planet : CelestialObject = sun.planets[0]

// RIGHT
let planet: CelestialObject = sun.planets[0]

// WRONG
class Planet : CelestialObject {
  // ...
}

// RIGHT
class Planet: CelestialObject {
  // ...
}

// WRONG
let moons: [Planet : Moon] = [
  mercury : [], 
  venus : [], 
  earth : [theMoon], 
  mars : [phobos,deimos],
]

// RIGHT
let moons: [Planet: Moon] = [
  mercury: [], 
  venus: [], 
  earth: [theMoon], 
  mars: [phobos,deimos],
]

(链接) 为了便于阅读，在返回箭头的两侧放置一个空格。

// WRONG
func doSomething()->String {
  // ...
}

// RIGHT
func doSomething() -> String {
  // ...
}

// WRONG
func doSomething(completion: ()->Void) {
  // ...
}

// RIGHT
func doSomething(completion: () -> Void) {
  // ...
}

(链接) 省略不必要的括号。

// WRONG
if (userCount > 0) { ... }
switch (someValue) { ... }
let evens = userCounts.filter { (number) in number.isMultiple(of: 2) }
let squares = userCounts.map() { $0 * $0 }

// RIGHT
if userCount > 0 { ... }
switch someValue { ... }
let evens = userCounts.filter { number in number.isMultiple(of: 2) }
let squares = userCounts.map { $0 * $0 }

(链接) 当所有参数都未标记时，从 case 语句中省略枚举关联值。

// WRONG
if case .done(_) = result { ... }

switch animal {
case .dog(_, _, _):
  ...
}

// RIGHT
if case .done = result { ... }

switch animal {
case .dog:
  ...
}

(链接) 当解构枚举的 case 或者元组时，将 let 关键字内联，紧邻每个单独的属性赋值。

// WRONG
switch result {
case let .success(value):
  // ...
case let .error(errorCode, errorReason):
  // ...
}

// WRONG
guard let case .success(value) else {
  return
}

// RIGHT
switch result {
case .success(let value):
  // ...
case .error(let errorCode, let errorReason):
  // ...
}

// RIGHT
guard case .success(let value) else {
  return
}

为什么？

一致性: 我们应该倾向于总是内联 let 关键字，或者从不内联 let 关键字。在 Airbnb 的 Swift 代码库中，我们观察到，内联 let 在实践中使用得更频繁（尤其是在解构带有单个关联值的枚举 case 时）。
清晰性: 内联 let 关键字可以更清楚地表明哪些标识符是条件检查的一部分，以及哪些标识符正在绑定新变量，因为 let 关键字始终紧邻变量标识符。

// `let` is adjacent to the variable identifier, so it is immediately obvious
// at a glance that these identifiers represent new variable bindings
case .enumCaseWithSingleAssociatedValue(let string):
case .enumCaseWithMultipleAssociatedValues(let string, let int):

// The `let` keyword is quite far from the variable identifiers,
// so it is less obvious that they represent new variable bindings
case let .enumCaseWithSingleAssociatedValue(string):
case let .enumCaseWithMultipleAssociatedValues(string, int):

(链接) 将函数、类型和计算属性的特性（attributes）放在声明的上一行。

// WRONG
@objc class Spaceship {

  @ViewBuilder var controlPanel: some View {
    // ...
  }

  @discardableResult func fly() -> Bool {
    // ...
  }

}

// RIGHT
@objc
class Spaceship {

  @ViewBuilder
  var controlPanel: some View {
    // ...
  }

  @discardableResult
  func fly() -> Bool {
    // ...
  }

}

(链接) 将存储属性的简单特性（attributes）放在与声明的其余部分同一行。具有命名参数或超过一个未命名参数的复杂特性，应放在上一行。

struct SpaceshipDashboardView {

  @State private var warpDriveEnabled: Bool

  @ObservedObject private var lifeSupportService: LifeSupportService

  @Environment(\.controlPanelStyle) private var controlPanelStyle
}

// RIGHT
struct SpaceshipDashboardView {

  @State
  private var warpDriveEnabled: Bool

  @ObservedObject
  private var lifeSupportService: LifeSupportService

  @Environment(\.controlPanelStyle) 
  private var controlPanelStyle
}

struct SolarSystemView {

  @Query(sort: \.distance) var allPlanets: [Planet]

  @Query(sort: \.age, order: .reverse) var moonsByAge: [Moon]

}

// RIGHT
struct SolarSystemView {

  @Query(sort: \.distance)
  var allPlanets: [Planet]

  @Query(sort: \.age, order: .reverse)
  var oldestMoons: [Moon]

}

// WRONG. These long, complex attributes should be written on the previous line.
struct RocketFactory {

  @available(*, unavailable, message: "No longer in production") var saturn5Builder: Saturn5Builder

  @available(*, deprecated, message: "To be retired by 2030") var atlas5Builder: Atlas5Builder

  @available(*, iOS 18.0, tvOS 18.0, macOS 15.0, watchOS 11.0) var newGlennBuilder: NewGlennBuilder

}

// RIGHT
struct RocketFactory {

  @available(*, unavailable, message: "No longer in production")
  var saturn5Builder: Saturn5Builder

  @available(*, deprecated, message: "To be retired by 2030")
  var atlas5Builder: Atlas5Builder
  
  @available(*, iOS 18.0, tvOS 18.0, macOS 15.0, watchOS 11.0)
  var newGlennBuilder: NewGlennBuilder

}

为什么？

与其他类型的声明（具有大括号并跨越多行）不同，存储属性声明通常只有一行代码。存储属性通常是连续编写的，它们之间没有任何空行。这使得代码紧凑而不影响可读性，并允许将相关属性分组在一起。

struct SpaceshipDashboardView {
  @State private var warpDriveEnabled: Bool
  @State private var lifeSupportEnabled: Bool
  @State private var artificialGravityEnabled: Bool
  @State private var tractorBeamEnabled: Bool
  
  @Environment(\.controlPanelStyle) private var controlPanelStyle
  @Environment(\.toggleButtonStyle) private var toggleButtonStyle
}

如果存储属性的特性（attributes）写在上一行（像其他类型的特性一样），那么属性开始在视觉上混合在一起，除非你在它们之间添加空行。

struct SpaceshipDashboardView {
  @State
  private var warpDriveEnabled: Bool
  @State
  private var lifeSupportEnabled: Bool
  @State
  private var artificialGravityEnabled: Bool
  @State
  private var tractorBeamEnabled: Bool
  
  @Environment(\.controlPanelStyle)
  private var controlPanelStyle
  @Environment(\.toggleButtonStyle)
  private var toggleButtonStyle
}

如果你添加空行，属性列表会变得更长，并且你失去了将相关属性分组在一起的能力。

struct SpaceshipDashboardView {
  @State
  private var warpDriveEnabled: Bool
  
  @State
  private var lifeSupportEnabled: Bool
  
  @State
  private var artificialGravityEnabled: Bool
  
  @State
  private var tractorBeamEnabled: Bool
  
  @Environment(\.controlPanelStyle)
  private var controlPanelStyle
  
  @Environment(\.toggleButtonStyle)
  private var toggleButtonStyle
}

这不适用于具有命名参数或多个未命名参数的复杂特性。这些参数在视觉上很复杂，并且通常编码大量信息，因此在单行上书写时会感到拥挤且难以阅读。

// Despite being less than 100 characters long, these lines are very complex and feel unnecessarily long: 
@available(*, unavailable, message: "No longer in production") var saturn5Builder: Saturn5Builder
@available(*, deprecated, message: "To be retired by 2030") var atlas5Builder: Atlas5Builder
@available(*, iOS 18.0, tvOS 18.0, macOS 15.0, watchOS 11.0) var newGlennBuilder: NewGlennBuilder

(链接) 多行数组的每个方括号应放在单独的行上。 将开始和结束括号放在与数组任何元素不同的行上。并在最后一个元素上添加尾随逗号。

// WRONG
let rowContent = [listingUrgencyDatesRowContent(),
                  listingUrgencyBookedRowContent(),
                  listingUrgencyBookedShortRowContent()]

// WRONG
let rowContent = [
  listingUrgencyDatesRowContent(),
  listingUrgencyBookedRowContent(),
  listingUrgencyBookedShortRowContent()
]

// RIGHT
let rowContent = [
  listingUrgencyDatesRowContent(),
  listingUrgencyBookedRowContent(),
  listingUrgencyBookedShortRowContent(),
]

(链接) 长协议组合的类型别名应在 = 之前和每个单独的 & 之前换行。

// WRONG (too long)
public typealias Dependencies = CivilizationServiceProviding & LawsOfPhysicsProviding & PlanetBuilderProviding & UniverseBuilderProviding & UniverseSimulatorServiceProviding

// WRONG (naive wrapping)
public typealias Dependencies = CivilizationServiceProviding & LawsOfPhysicsProviding & PlanetBuilderProviding &
  UniverseBuilderProviding & UniverseSimulatorServiceProviding

// WRONG (unbalanced)
public typealias Dependencies = CivilizationServiceProviding
  & LawsOfPhysicsProviding
  & PlanetBuilderProviding
  & UniverseBuilderProviding
  & UniverseSimulatorServiceProviding

// RIGHT
public typealias Dependencies
  = CivilizationServiceProviding
  & LawsOfPhysicsProviding
  & PlanetBuilderProviding
  & UniverseBuilderProviding
  & UniverseSimulatorServiceProviding

(链接) 按字母顺序排序协议组合类型别名。

为什么？

协议组合类型别名是一个无序列表，没有自然的排序。按字母顺序排序使这些列表更有条理，这对于长的协议组合尤其有价值。

// WRONG (not sorted)
public typealias Dependencies
  = UniverseBuilderProviding
  & LawsOfPhysicsProviding
  & UniverseSimulatorServiceProviding
  & PlanetBuilderProviding
  & CivilizationServiceProviding

// RIGHT
public typealias Dependencies
  = CivilizationServiceProviding
  & LawsOfPhysicsProviding
  & PlanetBuilderProviding
  & UniverseBuilderProviding
  & UniverseSimulatorServiceProviding

(链接) 当将可选属性解包为具有相同名称的非可选属性时，省略表达式的右侧。

为什么？

根据 SE-0345 中的原理，此简写语法消除了不必要的样板代码，同时保持了清晰度。

// WRONG
if
  let galaxy = galaxy,
  galaxy.name == "Milky Way"
{ … }

guard
  let galaxy = galaxy,
  galaxy.name == "Milky Way"
else { … }

// RIGHT
if
  let galaxy,
  galaxy.name == "Milky Way"
{ … }

guard
  let galaxy,
  galaxy.name == "Milky Way"
else { … }

(链接) Else 语句应与前一个条件的右大括号在同一行开始，除非条件之间用空行或注释分隔。

// WRONG
if let galaxy {
  …
}
else if let bigBangService {
  …
}
else {
  …
}

// RIGHT
if let galaxy {
  …
} else if let bigBangService {
  …
} else {
  …
}

// RIGHT, because there are comments between the conditions
if let galaxy {
  …
}
// If the galaxy hasn't been created yet, create it using the big bang service
else if let bigBangService {
  …
}
// If the big bang service doesn't exist, fail gracefully
else {
  …
}

// RIGHT, because there are blank lines between the conditions
if let galaxy {
  …
}

else if let bigBangService {
  // If the galaxy hasn't been created yet, create it using the big bang service
  …
}

else {
  // If the big bang service doesn't exist, fail gracefully
  …
}

(链接) 多行条件语句应在引导关键字后断行。 将每个单独的语句缩进 4 个空格。

为什么？

在引导关键字后断行会将缩进重置为标准的 4 个空格网格，这有助于避免与 Xcode 的 ^ + I 缩进行为作斗争。

// WRONG
if let galaxy,
  galaxy.name == "Milky Way" // Indenting by two spaces fights Xcode's ^+I indentation behavior
{ … }

// WRONG
guard let galaxy,
      galaxy.name == "Milky Way" // Variable width indentation (6 spaces)
else { … }

// WRONG
guard let earth = universe.find(
  .planet,
  named: "Earth"),
  earth.isHabitable // Blends in with previous condition's method arguments
else { … }

// RIGHT
if
  let galaxy,
  galaxy.name == "Milky Way"
{ … }

// RIGHT
guard
  let galaxy,
  galaxy.name == "Milky Way"
else { … }

// RIGHT
guard
  let earth = universe.find(
    .planet,
    named: "Earth"),
  earth.isHabitable
else { … }

// RIGHT
if let galaxy {
  …
}

// RIGHT
guard let galaxy else {
  …
}

(链接) 在多行 if 或 switch 表达式之前的赋值运算符 (=) 之后添加换行符，并缩进后面的 if / switch 表达式。如果声明适合单行，则不需要换行符。

为什么？

这使得 if 和 switch 表达式始终具有与标准 if 和 switch 语句相同的“形状”，其中

if / switch 关键字始终是专用代码行上的最左侧的标记。
条件分支始终位于 if / switch 关键字的右侧和下方。

这与 if / switch 关键字用于控制流的方式最为一致，因此可以更容易地一目了然地识别代码正在使用 if 或 switch 表达式。

// WRONG. Should have a line break after the first `=`. 
let planetLocation = if let star = planet.star {
  "The \(star.name) system"
 } else {
  "Rogue planet"
}

// WRONG. The first `=` should be on the line of the variable being assigned.
let planetLocation 
  = if let star = planet.star {
    "The \(star.name) system"
  } else {
    "Rogue planet"
  }

// WRONG. `switch` expression should be indented.
let planetLocation =
switch planet {
case .mercury, .venus, .earth, .mars:
  .terrestrial
case .jupiter, .saturn, .uranus, .neptune:
  .gasGiant
}
  
// RIGHT 
let planetLocation = 
  if let star = planet.star {
    "The \(star.name) system"
  } else {
    "Rogue planet"
  }
  
// RIGHT
let planetType: PlanetType =
  switch planet {
  case .mercury, .venus, .earth, .mars:
    .terrestrial
  case .jupiter, .saturn, .uranus, .neptune:
    .gasGiant
  }
  
// ALSO RIGHT. A line break is not required because the declaration fits on a single line. 
let moonName = if let moon = planet.moon { moon.name } else { "none" }

// ALSO RIGHT. A line break is permitted if it helps with readability.
let moonName =
  if let moon = planet.moon { moon.name } else { "none" }

(链接) 当使用条件语句（例如 if 或 switch 语句）的结果初始化新属性时，尽可能使用单个 if/switch 表达式，而不是定义未初始化的属性并在以下条件语句的每个分支上初始化它。

为什么？

与简单地在以下条件语句的每个分支上执行赋值相比，使用 if/switch 表达式有几个好处

在大多数情况下，您不再需要为要分配的变量显式编写类型注释。
编译器将诊断更多使用可变 var 不必要的情况。
生成的语法在视觉上更轻巧，因为不需要在每个分支上编写要分配的属性名称。

// BEFORE
// 1. An explicit type annotation is required for the uninitialized property.
// 2. `var` is unnecessary here because `planetLocation` is never modified after being initialized, but the compiler doesn't diagnose.
// 3. The `planetLocation` property name is written on each branch so is redundant and visually noisy.
var planetLocation: String
if let star = planet.star {
  planetLocation = "The \(star.name) system"
} else {
  planetLocation = "Rogue planet"
}

print(planetLocation)

// AFTER
// 1. No need to write an explicit `: String` type annotation.
// 2. The compiler correctly diagnoses that the `var` is unnecessary and emits a warning suggesting to use `let` instead. 
// 3. Each conditional branch is simply the value being assigned.
var planetLocation =
  if let star = planet.star {
    "The \(star.name) system"
  } else {
    "Rogue planet"
  }

print(planetLocation)

例子

// WRONG
let planetLocation: String
if let star = planet.star {
  planetLocation = "The \(star.name) system"
} else {
  planetLocation = "Rogue planet"
}

let planetType: PlanetType
switch planet {
case .mercury, .venus, .earth, .mars:
  planetType = .terrestrial
case .jupiter, .saturn, .uranus, .neptune:
  planetType = .gasGiant
}

let canBeTerraformed: Bool 
if 
  let star = planet.star, 
  !planet.isHabitable,
  planet.isInHabitableZone(of: star) 
{
  canBeTerraformed = true
} else {
  canBeTerraformed = false
}

// RIGHT
let planetLocation =
  if let star = planet.star {
    "The \(star.name) system"
  } else {
    "Rogue planet"
  }

let planetType: PlanetType =
  switch planet {
  case .mercury, .venus, .earth, .mars:
    .terrestrial
  case .jupiter, .saturn, .uranus, .neptune:
    .gasGiant
  }

let canBeTerraformed =
  if 
    let star = planet.star, 
    !planet.isHabitable,
    planet.isInHabitableZone(of: star) 
  {
    true
  } else {
    false
  }

// ALSO RIGHT. This example cannot be converted to an if/switch expression
// because one of the branches is more than just a single expression.
let planetLocation: String
if let star = planet.star {
  planetLocation = "The \(star.name) system"
} else {
  let actualLocaton = galaxy.name ?? "the universe"
  planetLocation = "Rogue planet somewhere in \(actualLocation)"
}

(链接) 在具有多行主体的 switch case 之后插入一个空行。 应该保持单个 switch 语句中的间距一致。如果任何 case 具有多行主体，则所有 case 都应包含尾随空行。最后一个 switch case 不需要空行，因为它已经跟随着一个右大括号。

为什么？

与文件中的声明一样，在范围之间插入空行使它们更容易在视觉上区分。

如果没有 case 之间的空行，复杂的 switch 语句在视觉上会非常繁忙，这使得读取代码更加困难，并且更难一目了然地区分单个 case。单个 case 之间的空行使复杂的 switch 语句更易于阅读。

例子

// WRONG. These switch cases should be followed by a blank line.
func handle(_ action: SpaceshipAction) {
  switch action {
  case .engageWarpDrive:
    navigationComputer.destination = targetedDestination
    warpDrive.spinUp()
    warpDrive.activate()
  case .enableArtificialGravity:
    artificialGravityEngine.enable(strength: .oneG)
  case .scanPlanet(let planet):
    scanner.target = planet
    scanner.scanAtmosphere()
    scanner.scanBiosphere()
    scanner.scanForArtificialLife()
  case .handleIncomingEnergyBlast:
    energyShields.engage()
  }
}

// WRONG. While the `.enableArtificialGravity` case isn't multi-line, the other cases are.
// For consistency, it should also include a trailing blank line.
func handle(_ action: SpaceshipAction) {
  switch action {
  case .engageWarpDrive:
    navigationComputer.destination = targetedDestination
    warpDrive.spinUp()
    warpDrive.activate()

  case .enableArtificialGravity:
    artificialGravityEngine.enable(strength: .oneG)
  case .scanPlanet(let planet):
    scanner.target = planet
    scanner.scanAtmosphere()
    scanner.scanBiosphere()
    scanner.scanForArtificialLife()
    
  case .handleIncomingEnergyBlast:
    energyShields.engage()
  }
}

// RIGHT. All of the cases have a trailing blank line.
func handle(_ action: SpaceshipAction) {
  switch action {
  case .engageWarpDrive:
    navigationComputer.destination = targetedDestination
    warpDrive.spinUp()
    warpDrive.activate()

  case .enableArtificialGravity:
    artificialGravityEngine.enable(strength: .oneG)

  case .scanPlanet(let planet):
    scanner.target = planet
    scanner.scanAtmosphere()
    scanner.scanBiosphere()
    scanner.scanForArtificialLife()
    
  case .handleIncomingEnergyBlast:
    energyShields.engage()
  }
}

// RIGHT. Since none of the cases are multi-line, blank lines are not required.
func handle(_ action: SpaceshipAction) {
  switch action {
  case .engageWarpDrive:
    warpDrive.engage()
  case .enableArtificialGravity:
    artificialGravityEngine.enable(strength: .oneG)
  case .scanPlanet(let planet):
    scanner.scan(planet)
  case .handleIncomingEnergyBlast:
    energyShields.engage()
  }
}

// ALSO RIGHT. Blank lines are still permitted after single-line switch cases if it helps with readability.
func handle(_ action: SpaceshipAction) {
  switch action {
  case .engageWarpDrive:
    warpDrive.engage()

  case .enableArtificialGravity:
    artificialGravityEngine.enable(strength: .oneG)

  case .scanPlanet(let planet):
    scanner.scan(planet)

  case .handleIncomingEnergyBlast:
    energyShields.engage()
  }
}

// WRONG. While it's fine to use blank lines to separate cases, spacing within a single switch statement should be consistent.
func handle(_ action: SpaceshipAction) {
  switch action {
  case .engageWarpDrive:
    warpDrive.engage()
  case .enableArtificialGravity:
    artificialGravityEngine.enable(strength: .oneG)
  case .scanPlanet(let planet):
    scanner.scan(planet)

  case .handleIncomingEnergyBlast:
    energyShields.engage()
  }
}

(链接) 在多行 guard 语句中，在 else 关键字之前添加换行符。 对于单行 guard 语句，将 else 关键字与 guard 关键字保持在同一行。左大括号应紧随 else 关键字。

// WRONG (else should be on its own line for multi-line guard statements)
guard
  let galaxy,
  galaxy.name == "Milky Way" else
{ … }

// WRONG (else should be on the same line for single-line guard statements)
guard let galaxy
else { … }

// RIGHT
guard
  let galaxy,
  galaxy.name == "Milky Way"
else { … }

// RIGHT
guard let galaxy else {
  …
}

(链接) 缩进多行字符串文字的正文和结束三引号，除非字符串文字在其自身的行上开始，在这种情况下，字符串文字内容和结束三引号应与开始三引号具有相同的缩进。

// WRONG
var spaceQuote = """
“Space,” it says, “is big. Really big. You just won’t believe how vastly, hugely, mindbogglingly big it is.
I mean, you may think it’s a long way down the road to the chemist’s, but that’s just peanuts to space.”
"""

// RIGHT
var spaceQuote = """
  “Space,” it says, “is big. Really big. You just won’t believe how vastly, hugely, mindbogglingly big it is.
  I mean, you may think it’s a long way down the road to the chemist’s, but that’s just peanuts to space.”
  """

// WRONG
var universeQuote: String {
  """
    In the beginning the Universe was created.
    This has made a lot of people very angry and been widely regarded as a bad move.
    """
}

// RIGHT
var universeQuote: String {
  """
  In the beginning the Universe was created.
  This has made a lot of people very angry and been widely regarded as a bad move.
  """
}

(链接) 使用构造器而不是 Make() 函数来创建 NSRange 和其他类型。

// WRONG
let range = NSMakeRange(10, 5)

// RIGHT
let range = NSRange(location: 10, length: 5)

(链接) 对于具有规范简写形式的标准库类型（Optional、Array、Dictionary），首选使用简写形式而不是完整的泛型形式。

// WRONG
let optional: Optional<String> = nil
let array: Array<String> = []
let dictionary: Dictionary<String, Any> = [:]

// RIGHT
let optional: String? = nil
let array: [String] = []
let dictionary: [String: Any] = [:]

(链接) 在不需要时省略显式的 .init。

// WRONG
let universe = Universe.init()

// RIGHT
let universe = Universe()

(链接) 单行表达式后的左大括号应与该语句的其余部分位于同一行。

// WRONG
if !planet.isHabitable
{
  planet.terraform()
}

class Planet
{
  func terraform()
  {
    generateAtmosphere()
    generateOceans()
  }
}

// RIGHT
if !planet.isHabitable {
  planet.terraform()
}

class Planet {
  func terraform() {
    generateAtmosphere()
    generateOceans()
  }
}

(链接) 多行表达式后的左大括号应换行。

// WRONG
if
  let star = planet.nearestStar(),
  planet.isInHabitableZone(of: star) {
  planet.terraform()
}

class Planet {
  func terraform(
    atmosphereOptions: AtmosphereOptions = .default,
    oceanOptions: OceanOptions = .default) {
    generateAtmosphere(atmosphereOptions)
    generateOceans(oceanOptions)
  }
}

// RIGHT
if
  let star = planet.nearestStar(),
  planet.isInHabitableZone(of: star)
{
  planet.terraform()
}

class Planet {
  func terraform(
    atmosphereOptions: AtmosphereOptions = .default,
    oceanOptions: OceanOptions = .default
  ) {
    generateAtmosphere(atmosphereOptions)
    generateOceans(oceanOptions)
  }
}

(链接) 大括号的每一侧都应该用一个空格字符（空格或换行符）包围。

// WRONG
struct Planet{
  …
}

// WRONG
if condition{
  …
}else{
  …
}

// RIGHT
struct Planet {
  …
}

// RIGHT
if condition {
  …
} else {
  …
}

(链接) 对于函数调用和声明，参数列表的括号前后和内部不应有空格。

// WRONG
func install ( _ engine: Engine ) { }

install ( AntimatterDrive( ) )

// RIGHT
func install(_ engine: Engine) { }

install(AntimatterDrive())

(链接) 注释块应使用单行注释（代码注释使用 //，文档注释使用 ///），而不是多行注释（/* ... */ 和 /** ... */）。

// WRONG

/**
* A planet that exists somewhere in the universe.
*
* Planets have many properties. For example, the best planets
* have atmospheres and bodies of water to support life.
*/
class Planet {
  /**
    Terraforms the planet, by adding an atmosphere and ocean that is hospitable for life.
  */
  func terraform() {
    /*
    Generate the atmosphere first, before generating the ocean.
    Otherwise, the water will just boil off immediately.
    */
    generateAtmosphere()

    /* Now that we have an atmosphere, it's safe to generate the ocean */
    generateOceans()
  }
}

// RIGHT

/// A planet that exists somewhere in the universe.
///
/// Planets have many properties. For example, the best planets
/// have atmospheres and bodies of water to support life.
class Planet {
  /// Terraforms the planet, by adding an atmosphere and ocean that is hospitable for life.
  func terraform() {
    // Generate the atmosphere first, before generating the ocean.
    // Otherwise, the water will just boil off immediately.
    generateAtmosphere()

    // Now that we have an atmosphere, it's safe to generate the ocean
    generateOceans()
  }
}

(链接) 在类型主体内或顶层级别的声明之前，使用文档注释 (///) 代替常规注释 (//)。

// WRONG

// A planet that exists somewhere in the universe.
class Planet {
  // Data about the composition and density of the planet's atmosphere if present.
  var atmosphere: Atmosphere?

  // Data about the size, location, and composition of large bodies of water on the planet's surface.
  var oceans: [Ocean]

  // Terraforms the planet, by adding an atmosphere and ocean that is hospitable for life.
  func terraform() {
    // This gas composition has a pretty good track record so far!
    let composition = AtmosphereComposition(nitrogen: 0.78, oxygen: 0.22)

    // Generate the atmosphere first, then the oceans. Otherwise, the water will just boil off immediately.
    generateAtmosphere(using: composition)
    generateOceans()
  }
}

// RIGHT

/// A planet that exists somewhere in the universe.
class Planet {
  /// Data about the composition and density of the planet's atmosphere if present.
  var atmosphere: Atmosphere?

  /// Data about the size, location, and composition of large bodies of water on the planet's surface.
  var oceans: [Ocean]

  /// Terraforms the planet, by adding an atmosphere and ocean that is hospitable for life.
  func terraform() {
    // This gas composition has a pretty good track record so far!
    let composition = AtmosphereComposition(nitrogen: 0.78, oxygen: 0.22)

    // Generate the atmosphere first, then the oceans. Otherwise, the water will just boil off immediately.
    generateAtmosphere(using: composition)
    generateOceans()
  }
}

// ALSO RIGHT:

func terraform() {
  /// This gas composition has a pretty good track record so far!
  ///  - Doc comments are not required before local declarations in function scopes, but are permitted.
  let composition = AtmosphereComposition(nitrogen: 0.78, oxygen: 0.22)

  /// Generate the `atmosphere` first, **then** the `oceans`. Otherwise, the water will just boil off immediately.
  ///  - Comments not preceding declarations can use doc comments, and will not be autocorrected into regular comments.
  ///    This can be useful because Xcode applies markdown styling to doc comments but not regular comments.
  generateAtmosphere(using: composition)
  generateOceans()
}

在某些情况下，允许在声明之前使用常规注释。

例如，像 // swiftformat:, // swiftlint:, // sourcery:, // MARK: 和 // TODO: 这样的注释指令通常需要使用常规注释，并且不能与文档注释一起正确工作。

// RIGHT

// swiftformat:sort
enum FeatureFlags {
  case allowFasterThanLightTravel
  case disableGravity
  case enableDarkEnergy
  case enableDarkMatter
}

// TODO: There are no more production consumers of this legacy model, so we
// should detangle the remaining code dependencies and clean it up.
struct LegacyGeocentricUniverseModel {
  ...
}

在一组声明块之前也允许使用常规注释，因为该注释可能指的是整个块，而不仅仅是后面的声明。

// RIGHT

enum Planet {
  // The inner planets
  case mercury
  case venus
  case earth
  case mars

  // The outer planets
  case jupiter
  case saturn
  case uranus
  case neptune
}

// ALSO RIGHT

enum Planet {
  /// The smallest planet
  case mercury
  case venus
  case earth
  case mars
  /// The largest planet
  case jupiter
  case saturn
  case uranus
  case neptune
}

(链接) 将声明的文档注释放在任何属性或修饰符之前。

// WRONG

@MainActor
/// A spacecraft with everything you need to explore the universe.
struct Spaceship { … }

public
/// A spacecraft with everything you need to explore the universe.
struct Spaceship { … }

// RIGHT

/// A spacecraft with everything you need to explore the universe.
@MainActor
struct Spaceship { … }

/// A spacecraft with everything you need to explore the universe.
public struct Spaceship { … }

(链接) 在注释分隔符（//、///、/* 和 */）前后包含空格或换行符。

// WRONG

///A spacecraft with incredible performance characteristics
struct Spaceship {

  func travelFasterThanLight() {/*unimplemented*/}

  func travelBackInTime() { }//TODO: research whether or not this is possible

}

// RIGHT

/// A spacecraft with incredible performance characteristics
struct Spaceship {

  func travelFasterThanLight() { /* unimplemented */ }

  func travelBackInTime() { } // TODO: research whether or not this is possible

}

(链接) 在空的括号 ({ }) 中包含一个空格。

// WRONG
extension Spaceship: Trackable {}

extension SpaceshipView {
  var accessibilityIdentifier: String {
    get { spaceship.name }
    set {}
  }
}

// RIGHT
extension Spaceship: Trackable { }

extension SpaceshipView {
  var accessibilityIdentifier: String {
    get { spaceship.name }
    set { }
  }
}

(链接) 除非将 forEach(…) 用作函数式链中的最后一个元素，否则应优先使用 for 循环而不是函数式 forEach(…) 方法。
为什么？

For 循环比 forEach(…) 方法更符合习惯用法，并且通常为所有具有 C 系列语言经验的开发人员所熟悉。

For 循环也比 forEach(…) 方法更具表现力。 For 循环支持 return、continue 和 break 控制流关键字，而 forEach(…) 仅支持 return（其行为与 for 循环中的 continue 相同）。
```
// WRONG
planets.forEach { planet in
  planet.terraform()
}

// WRONG
planets.forEach {
  $0.terraform()
}

// RIGHT
for planet in planets {
  planet.terraform()
}

// ALSO FINE, since forEach is useful when paired with other functional methods in a chain.
planets
  .filter { !$0.isGasGiant }
  .map { PlanetTerraformer(planet: $0) }
  .forEach { $0.terraform() }
```

(链接) 定义具有 internal 访问控制级别的类型、属性或函数时，省略 internal 关键字。

// WRONG
internal class Spaceship {
  internal init() { … }

  internal func travel(to planet: Planet) { … }
}

// RIGHT, because internal access control is implied if no other access control level is specified.
class Spaceship {
  init() { … }

  func travel(to planet: Planet) { … }
}

函数

(链接) 从函数定义中省略 Void 返回类型。

// WRONG
func doSomething() -> Void {
  ...
}

// RIGHT
func doSomething() {
  ...
}

(链接) 在每个参数标签之前，以及在返回签名或任何效果（async、throws）之前，使用换行符分隔长函数声明。 将左大括号放在下一行，这样第一条可执行行看起来不像另一个参数。

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
  }

  // WRONG
  func generateStars(
    at location: Point,
    count: Int,
    color: StarColor,
    withAverageDistance averageDistance: Float) async throws // these effects are easy to miss since they're visually associated with the last parameter
    -> String
  {
    populateUniverse()
  }

  // 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
  ) async throws -> String {
    populateUniverse()
  }
}

(链接) 长函数调用也应在每个参数上断开。 将右括号放在调用的最后一行。

// 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)

(链接) 将未使用的函数参数命名为下划线 (_)。

为什么？

将未使用的函数参数命名为下划线可以更清楚地表明该参数在函数体中未使用。这可以更容易地发现细微的逻辑错误，并可以突出显示简化方法签名的机会。

// WRONG

// In this method, the `newCondition` parameter is unused.
// This is actually a logical error, and is easy to miss, but compiles without warning.
func updateWeather(_ newCondition: WeatherCondition) -> Weather {
  var updatedWeather = self
  updatedWeather.condition = condition // this mistake inadvertently makes this method unable to change the weather condition
  return updatedWeather
}

// In this method, the `color` parameter is unused.
// Is this a logical error (e.g. should it be passed through to the `universe.generateStars` method call),
// or is this an unused argument that should be removed from the method signature?
func generateUniverseWithStars(
  at location: Point,
  count: Int,
  color: StarColor,
  withAverageDistance averageDistance: Float)
{
  let universe = generateUniverse()
  universe.generateStars(
    at: location,
    count: count,
    withAverageDistance: averageDistance)
}

// RIGHT

// Automatically reformatting the unused parameter to be an underscore
// makes it more clear that the parameter is unused, which makes it
// easier to spot the logical error.
func updateWeather(_: WeatherCondition) -> Weather {
  var updatedWeather = self
  updatedWeather.condition = condition
  return updatedWeather
}

// The underscore makes it more clear that the `color` parameter is unused.
// This method argument can either be removed if truly unnecessary,
// or passed through to `universe.generateStars` to correct the logical error.
func generateUniverseWithStars(
  at location: Point,
  count: Int,
  color _: StarColor,
  withAverageDistance averageDistance: Float)
{
  let universe = generateUniverse()
  universe.generateStars(
    at: location,
    count: count,
    withAverageDistance: averageDistance)
}

(链接) 删除链式函数之间的空行。

为什么？

提高可读性和可维护性，使其更容易看到应用于对象的函数序列。

// WRONG
var innerPlanetNames: [String] {
  planets
    .filter { $0.isInnerPlanet }

    .map { $0.name }
}

// WRONG
var innerPlanetNames: [String] {
  planets
    .filter { $0.isInnerPlanet }

    // Gets the name of the inner planet
    .map { $0.name }
}

// RIGHT
var innerPlanetNames: [String] {
  planets
    .filter { $0.isInnerPlanet }
    .map { $0.name }
}

// RIGHT
var innerPlanetNames: [String] {
  planets
    .filter { $0.isInnerPlanet }
    // Gets the name of the inner planet
    .map { $0.name }
}

闭包

(链接) 在闭包声明中，优先使用 Void 返回类型而不是 ()。 如果您必须在函数声明中指定 Void 返回类型，请使用 Void 而不是 () 以提高可读性。
```
// WRONG
func method(completion: () -> ()) {
  ...
}

// RIGHT
func method(completion: () -> Void) {
  ...
}
```
(链接) 将未使用的闭包参数命名为下划线 (_)。
为什么？

将未使用的闭包参数命名为下划线，通过明确哪些参数被使用和哪些参数未被使用，从而减少了阅读闭包所需的认知开销。
```
// WRONG
someAsyncThing() { argument1, argument2, argument3 in
  print(argument3)
}

// RIGHT
someAsyncThing() { _, _, argument3 in
  print(argument3)
}
```

(链接) 闭包的大括号内部应包含单个空格或换行符。 尾随闭包的大括号外部还应包含单个空格或换行符。

// WRONG
let evenSquares = numbers.filter{$0.isMultiple(of: 2)}.map{  $0 * $0  }

// RIGHT
let evenSquares = numbers.filter { $0.isMultiple(of: 2) }.map { $0 * $0 }

// WRONG
let evenSquares = numbers.filter( { $0.isMultiple(of: 2) } ).map( { $0 * $0 } )

// RIGHT
let evenSquares = numbers.filter({ $0.isMultiple(of: 2) }).map({ $0 * $0 })

// WRONG
let evenSquares = numbers
  .filter{
    $0.isMultiple(of: 2)
  }
  .map{
    $0 * $0
  }

// RIGHT
let evenSquares = numbers
  .filter {
    $0.isMultiple(of: 2)
  }
  .map {
    $0 * $0
  }

(链接) 从闭包表达式中省略 Void 返回类型。

// WRONG
someAsyncThing() { argument -> Void in
  ...
}

// RIGHT
someAsyncThing() { argument in
  ...
}

(链接) 对于没有参数名称的闭包参数，首选尾随闭包语法。

// WRONG
planets.map({ $0.name })

// RIGHT
planets.map { $0.name }

// ALSO RIGHT, since this closure has a parameter name
planets.first(where: { $0.isGasGiant })

// ALSO FINE. Trailing closure syntax is still permitted for closures
// with parameter names. However, consider using non-trailing syntax
// in cases where the parameter name is semantically meaningful.
planets.first { $0.isGasGiant }

(链接) 避免使用 unowned 捕获。 而是首选更安全的选择，例如 weak 捕获，或直接捕获变量。

unowned 捕获是不安全的，因为如果引用的对象已被释放，它们将导致应用程序崩溃。

// WRONG: Crashes if `self` has been deallocated when closures are called.
final class SpaceshipNavigationService {
  let spaceship: Spaceship
  let planet: Planet
  
  func colonizePlanet() {
    spaceship.travel(to: planet, onArrival: { [unowned self] in
      planet.colonize()
    })
  }
  
  func exploreSystem() {
    spaceship.travel(to: planet, nextDestination: { [unowned self] in
      planet.moons?.first
    })
  }
}

weak 捕获更安全，因为它们要求作者显式处理引用的对象不再存在的情况。

// RIGHT: Uses a `weak self` capture and explicitly handles the case where `self` has been deallocated
final class SpaceshipNavigationService {
  let spaceship: Spaceship
  let planet: Planet
  
  func colonizePlanet() {
    spaceship.travel(to: planet, onArrival: { [weak self] in
      guard let self else { return }
      planet.colonize()
    })
  }
  
  func exploreSystem() {
    spaceship.travel(to: planet, nextDestination: { [weak self] in
      guard let self else { return nil }
      return planet.moons?.first
    })
  }
}

或者，考虑直接捕获闭包中使用的变量。这样您就可以避免处理 self 为 nil 的情况，因为您甚至不需要引用 self

// RIGHT: Explicitly captures `planet` instead of capturing `self`
final class SpaceshipNavigationService {
  let spaceship: Spaceship
  let planet: Planet
  
  func colonizePlanet() {
    spaceship.travel(to: planet, onArrival: { [planet] in
      planet.colonize()
    })
  }
  
  func exploreSystem() {
    spaceship.travel(to: planet, nextDestination: { [planet] in
      planet.moons?.first
    })
  }
}

运算符

(链接) 中缀运算符的两侧应包含一个空格。 但是，在运算符定义中，省略运算符和左括号之间的尾随空格。此规则不适用于范围运算符（例如 1...3）。

// WRONG
let capacity = 1+2
let capacity = currentCapacity??0
let capacity=newCapacity
let latitude = region.center.latitude-region.span.latitudeDelta/2.0

// RIGHT
let capacity = 1 + 2
let capacity = currentCapacity ?? 0
let capacity = newCapacity
let latitude = region.center.latitude - region.span.latitudeDelta / 2.0

// WRONG
static func == (_ lhs: MyView, _ rhs: MyView) -> Bool {
  lhs.id == rhs.id
}

// RIGHT
static func ==(_ lhs: MyView, _ rhs: MyView) -> Bool {
  lhs.id == rhs.id
}

(链接) 长三元运算符表达式应在 ? 之前和 : 之前换行，将每个条件分支放在单独的行上。

// WRONG (too long)
let destinationPlanet = solarSystem.hasPlanetsInHabitableZone ? solarSystem.planetsInHabitableZone.first : solarSystem.uninhabitablePlanets.first

// WRONG (naive wrapping)
let destinationPlanet = solarSystem.hasPlanetsInHabitableZone ? solarSystem.planetsInHabitableZone.first :
  solarSystem.uninhabitablePlanets.first

// WRONG (unbalanced operators)
let destinationPlanet = solarSystem.hasPlanetsInHabitableZone ?
  solarSystem.planetsInHabitableZone.first :
  solarSystem.uninhabitablePlanets.first

// RIGHT
let destinationPlanet = solarSystem.hasPlanetsInHabitableZone
  ? solarSystem.planetsInHabitableZone.first
  : solarSystem.uninhabitablePlanets.first

(链接) 在条件语句 (if, guard, while) 中，使用逗号 (,) 而不是 && 运算符分隔布尔条件。

// WRONG
if let star = planet.star, !planet.isHabitable && planet.isInHabitableZone(of: star) {
  planet.terraform()
}

if
  let star = planet.star,
  !planet.isHabitable
  && planet.isInHabitableZone(of: star)
{
  planet.terraform()
}

// RIGHT
if let star = planet.star, !planet.isHabitable, planet.isInHabitableZone(of: star) {
  planet.terraform()
}

if
  let star = planet.star,
  !planet.isHabitable,
  planet.isInHabitableZone(of: star)
{
  planet.terraform()
}

(链接) 扩展绑定泛型类型时，首选使用泛型括号语法 (extension Collection<Planet>)，或适用于标准库类型的简写语法 (extension [Planet]) 而不是泛型类型约束。

// WRONG
extension Array where Element == Star { … }
extension Optional where Wrapped == Spaceship { … }
extension Dictionary where Key == Moon, Element == Planet { … }
extension Collection where Element == Universe { … }
extension StateStore where State == SpaceshipState, Action == SpaceshipAction { … }

// RIGHT
extension [Star] { … }
extension Spaceship? { … }
extension [Moon: Planet] { … }
extension Collection<Universe> { … }
extension StateStore<SpaceshipState, SpaceshipAction> { … }

// ALSO RIGHT. There are multiple types that could satisfy this constraint
// (e.g. [Planet], [Moon]), so this is not a "bound generic type" and isn't
// eligible for the generic bracket syntax.
extension Array where Element: PlanetaryBody { }

(链接) 避免使用分号。 行尾不需要分号，因此应省略。虽然您可以使用分号将两个语句放在同一行上，但更常见和首选的方法是使用换行符分隔它们。

例子

// WRONG. Semicolons are not required and can be omitted.
let mercury = planets[0];
let venus = planets[1];
let earth = planets[2];

// WRONG. While you can use semicolons to place multiple statements on a single line,
// it is more common and preferred to separate them using newlines instead.
let mercury = planets[0]; let venus = planets[1]; let earth = planets[2];

// RIGHT
let mercury = planets[0]
let venus = planets[1]
let earth = planets[2]

// WRONG
guard let moon = planet.moon else { completion(nil); return }

// WRONG
guard let moon = planet.moon else { 
  completion(nil); return
}

// RIGHT
guard let moon = planet.moon else { 
  completion(nil)
  return
}

⬆ 返回顶部

模式

(链接) 尽可能在 init 时初始化属性，而不是使用隐式解包的可选项。 一个值得注意的例外是 UIViewController 的 view 属性。

// WRONG
class MyClass {

  init() {
    super.init()
    someValue = 5
  }

  var someValue: Int!
}

// RIGHT
class MyClass {

  init() {
    someValue = 0
    super.init()
  }

  var someValue: Int
}

(链接) 避免在 init() 中执行任何有意义或耗时的工作。 避免执行诸如打开数据库连接、发出网络请求、从磁盘读取大量数据等操作。如果在对象准备好使用之前需要完成这些操作，请创建一个类似 start() 的方法。

(链接) 将复杂的属性观察器提取到方法中。 这样可以减少嵌套，将副作用与属性声明分开，并使隐式传递的参数（如 oldValue）的使用更加明确。

// 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.
  }
}

(链接) 将复杂的回调块提取到方法中。这样可以限制由块中的 weak-self 引入的复杂性，并减少嵌套。如果需要在方法调用中引用 self，请使用 guard 来解包 self 以便在回调期间使用。

// WRONG
class MyClass {

  func request(completion: () -> Void) {
    API.request() { [weak self] response in
      if let self {
        // Processing and side effects
      }
      completion()
    }
  }
}

// RIGHT
class MyClass {

  func request(completion: () -> Void) {
    API.request() { [weak self] response in
      guard let self else { return }
      self.doSomething(with: self.property, response: response)
      completion()
    }
  }

  func doSomething(with nonOptionalParameter: SomeClass, response: SomeResponseClass) {
    // Processing and side effects
  }
}

(链接) 首选在范围的开头使用 guard。

为什么？

当所有 guard 语句都组合在顶部而不是与业务逻辑混合在一起时，更容易推理代码块。

(链接) 访问控制应尽可能处于最严格的级别。 除非您需要该行为，否则首选 public 而不是 open，首选 private 而不是 fileprivate。

// WRONG
public struct Spaceship {
  // WRONG: `engine` is used in `extension Spaceship` below,
  // but extensions in the same file can access `private` members.
  fileprivate let engine: AntimatterEngine

  // WRONG: `hull` is not used by any other type, so `fileprivate` is unnecessary.
  fileprivate let hull: Hull

  // RIGHT: `navigation` is used in `extension Pilot` below,
  // so `fileprivate` is necessary here.
  fileprivate let navigation: SpecialRelativityNavigationService
}

extension Spaceship {
  public func blastOff() {
    engine.start()
  }
}

extension Pilot {
  public func chartCourse() {
    spaceship.navigation.course = .andromedaGalaxy
    spaceship.blastOff()
  }
}

// RIGHT
public struct Spaceship {
  fileprivate let navigation: SpecialRelativityNavigationService
  private let engine: AntimatterEngine
  private let hull: Hull
}

extension Spaceship {
  public func blastOff() {
    engine.start()
  }
}

extension Pilot {
  public func chartCourse() {
    spaceship.navigation.course = .andromedaGalaxy
    spaceship.blastOff()
  }
}

(链接) 尽可能避免全局函数。 首选类型定义中的方法。

// WRONG
func age(of person: Person, bornAt: TimeInterval) -> Int {
  // ...
}

func jump(person: Person) {
  // ...
}

// RIGHT
class Person {
  var bornAt: TimeInterval

  var age: Int {
    // ...
  }

  func jump() {
    // ...
  }
}

(链接) 使用无实例的 enum 将 public 或 internal 常量和函数组织到命名空间中。
- 避免创建非命名空间的全局常量和函数。
- 如果添加清晰度，请随意嵌套命名空间。
- 允许使用 private 全局变量，因为它们的作用域限定为单个文件，并且不会污染全局命名空间。考虑将私有全局变量放在 enum 命名空间中，以匹配其他声明类型的指南。
为什么？

无实例的 enum 非常适合作为命名空间，因为它们无法实例化，这符合它们的意图。
```
// WRONG
struct Environment {
  static let earthGravity = 9.8
  static let moonGravity = 1.6
}

// WRONG
struct Environment {

  struct Earth {
    static let gravity = 9.8
  }

  struct Moon {
    static let gravity = 1.6
  }
}

// RIGHT
enum Environment {

  enum Earth {
    static let gravity = 9.8
  }

  enum Moon {
    static let gravity = 1.6
  }
}
```

(链接) 除非 Swift 的自动枚举值映射到外部来源，否则使用它们。 添加注释以解释为什么定义显式值。

为什么？

为了最大限度地减少用户错误、提高可读性并更快地编写代码，请依赖 Swift 的自动枚举值。但是，如果该值映射到外部来源（例如，它来自网络请求）或跨二进制文件持久存在，则显式定义这些值，并记录这些值映射到的内容。

这样可以确保如果有人在中间添加新值，他们不会意外地破坏任何东西。

// WRONG
enum ErrorType: String {
  case error = "error"
  case warning = "warning"
}

// WRONG
enum UserType: String {
  case owner
  case manager
  case member
}

// WRONG
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
}

// WRONG
enum ErrorCode: Int {
  case notEnoughMemory
  case invalidResource
  case timeOut
}

// RIGHT
// Relying on Swift's automatic enum values
enum ErrorType: String {
  case error
  case warning
}

// RIGHT
/// These are written to a logging service. Explicit values ensure they're consistent across binaries.
// swiftformat:disable redundantRawValues
enum UserType: String {
  case owner = "owner"
  case manager = "manager"
  case member = "member"
}
// swiftformat:enable redundantRawValues

// RIGHT
// Relying on Swift's automatic enum values
enum Planet: Int {
  case mercury
  case venus
  case earth
  case mars
  case jupiter
  case saturn
  case uranus
  case neptune
}

// RIGHT
/// 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
}

(链接) 仅当可选值具有语义含义时才使用它们。

(链接) 尽可能首选不可变值。 使用 map 和 compactMap 而不是附加到新集合。使用 filter 而不是从可变集合中删除元素。

为什么？

可变变量会增加复杂性，因此尽量将它们保持在尽可能窄的范围内。

// 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) }

(链接) 尽可能首选不可变或计算的静态属性，而不是可变属性。 尽可能使用存储的 static let 属性或计算的 static var 属性，而不是存储的 static var 属性，因为存储的 static var 属性是全局可变状态。

为什么？

全局可变状态会增加复杂性，并使推理应用程序的行为变得更加困难。应尽可能避免它。

// WRONG
enum Fonts {
  static var title = UIFont(…)
}

// RIGHT
enum Fonts {
  static let title = UIFont(…)
}

// WRONG
struct FeatureState {
  var count: Int

  static var initial = FeatureState(count: 0)
}

// RIGHT
struct FeatureState {
  var count: Int

  static var initial: FeatureState {
    // Vend static properties that are cheap to compute
    FeatureState(count: 0)
  }
}

(链接) 使用 assert 方法处理意外但可恢复的情况，并结合在生产环境中进行适当的日志记录。如果意外情况不可恢复，则首选 precondition 方法或 fatalError()。这在崩溃和提供对野外意外情况的洞察之间取得了平衡。只有在故障消息是动态的时才首选 fatalError 而不是 precondition 方法，因为 precondition 方法不会在崩溃报告中报告该消息。

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
}

(链接) 默认将类型方法设置为 static。

为什么？

如果需要重写某个方法，则作者应通过使用 class 关键字选择该功能。

// WRONG
class Fruit {
  class func eatFruits(_ fruits: [Fruit]) { ... }
}

// RIGHT
class Fruit {
  static func eatFruits(_ fruits: [Fruit]) { ... }
}

(链接) 默认将类设置为 final。
为什么？

如果需要重写某个类，则作者应通过省略 final 关键字选择该功能。
```
// WRONG
class SettingsRepository {
  // ...
}

// RIGHT
final class SettingsRepository {
  // ...
}
```

(链接) 当切换枚举时，通常首选枚举所有情况，而不是使用 default 情况。

为什么？

枚举每种情况要求开发人员和审阅者在将来添加新情况时必须考虑每个 switch 语句的正确性。

// NOT PREFERRED
switch trafficLight {
case .greenLight:
  // Move your vehicle
default:
  // Stop your vehicle
}

// PREFERRED
switch trafficLight {
case .greenLight:
  // Move your vehicle
case .yellowLight, .redLight:
  // Stop your vehicle
}

// COUNTEREXAMPLES

enum TaskState {
  case pending
  case running
  case canceling
  case success(Success)
  case failure(Error)

  // We expect that this property will remain valid if additional cases are added to the enumeration.
  public var isRunning: Bool {
    switch self {
    case .running:
      true
    default:
      false
    }
  }  
}

extension TaskState: Equatable {
  // Explicitly listing each state would be too burdensome. Ideally this function could be implemented with a well-tested macro.
  public static func == (lhs: TaskState, rhs: TaskState) -> Bool {
    switch (lhs, rhs) {
    case (.pending, .pending):
      true
    case (.running, .running):
      true
    case (.canceling, .canceling):
      true
    case (.success(let lhs), .success(let rhs)):
      lhs == rhs
    case (.failure(let lhs), .failure(let rhs)):
      lhs == rhs
    default:
      false
    }
  }
}

(链接) 如果不需要使用值，则检查 nil，而不是使用可选绑定。
为什么？

检查 nil 可以立即明确语句的意图。可选绑定则不太明确。
```
var thing: Thing?

// WRONG
if let _ = thing {
  doThing()
}

// RIGHT
if thing != nil {
  doThing()
}
```

(链接) 在语言不需要时，省略 return 关键字。

// 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)
}

var alertTitle: String {
  if issue.severity == .critical {
    return "💥 Critical Error"
  } else {
    return "ℹ️ Info"
  }
}

func type(of planet: Planet) -> PlanetType {
  switch planet {
  case .mercury, .venus, .earth, .mars:
    return .terrestrial
  case .jupiter, .saturn, .uranus, .neptune:
    return .gasGiant
  }
}

// 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)
}

var alertTitle: String {
  if issue.severity == .critical {
    "💥 Critical Error"
  } else {
    "ℹ️ Info"
  }
}

func type(of planet: Planet) -> PlanetType {
  switch planet {
  case .mercury, .venus, .earth, .mars:
    .terrestrial
  case .jupiter, .saturn, .uranus, .neptune:
    .gasGiant
  }
}

(链接) 在协议定义中使用 AnyObject 而不是 class。
为什么？

SE-0156，引入了使用 AnyObject 关键字作为协议约束的支持，建议优先使用 AnyObject 而不是 class。

这个提案合并了 class 和 AnyObject 的概念，它们现在具有相同的含义：它们代表类的存在类型。为了消除重复，我们建议只保留 AnyObject。为了最大限度地减少源代码中断，可以将 class 重新定义为 typealias class = AnyObject，并在实现此提案的第一个 Swift 版本中给出关于 class 的弃用警告。稍后，可以在随后的 Swift 版本中删除 class。
```
// WRONG
protocol Foo: class { }

// RIGHT
protocol Foo: AnyObject { }
```

(链接) 在扩展中单独为每个声明指定访问控制。

为什么？

在声明本身上指定访问控制有助于工程师更快地确定单个声明的访问控制级别。

// WRONG
public extension Universe {
  // This declaration doesn't have an explicit access control level.
  // In all other scopes, this would be an internal function,
  // but because this is in a public extension, it's actually a public function.
  func generateGalaxy() { }
}

// WRONG
private extension Spaceship {
  func enableHyperdrive() { }
}

// RIGHT
extension Universe {
  // It is immediately obvious that this is a public function,
  // even if the start of the `extension Universe` scope is off-screen.
  public func generateGalaxy() { }
}

// RIGHT
extension Spaceship {
  // Recall that a private extension actually has fileprivate semantics,
  // so a declaration in a private extension is fileprivate by default.
  fileprivate func enableHyperdrive() { }
}

(链接) 优先使用专门的日志记录系统，例如 os_log 或 swift-log，而不是使用 print(…)、debugPrint(…) 或 dump(…) 直接写入标准输出。

为什么？

所有日志消息都应流入中间日志记录系统，这些系统可以将消息定向到正确的目的地，并可能根据应用程序的环境或配置过滤消息。 print(…)、debugPrint(…) 或 dump(…) 会在所有应用程序配置中将所有消息直接写入标准输出，并且可能会泄露个人身份信息 (PII)。
(链接) 不要使用 #file。适当使用 #fileID 或 #filePath。

为什么？

#file 字面量（或者从 Swift 5.9 开始的宏）的行为已经从评估为完整的源文件路径（#filePath 的行为）演变为包含模块和文件名称的可读字符串（#fileID 的行为）。使用最适合您的用例的字面量（或宏）。

Swift 文档

Swift Evolution 提案：简洁的魔术文件名
(链接) 不要在生产代码中使用 #filePath。使用 #fileID 代替。

为什么？

#filePath 应该只在非生产代码中使用，其中源文件的完整路径为开发人员提供有用的信息。因为 #fileID 不会嵌入到源文件的完整路径，所以它不会暴露你的文件系统，并减小了编译后的二进制文件的大小。

#filePath 文档

(链接) 避免总是立即调用的单表达式闭包。 相反，倾向于内联表达式。

// WRONG
lazy var universe: Universe = {
  Universe()
}()

lazy var stars = {
  universe.generateStars(
    at: location,
    count: 5,
    color: starColor,
    withAverageDistance: 4)
}()

// RIGHT
lazy var universe = Universe()

lazy var stars = universe.generateStars(
  at: location,
  count: 5,
  color: starColor,
  withAverageDistance: 4)

(链接) 从不包含 set、willSet 或 didSet 子句的计算属性声明中省略 get 子句。

// WRONG
var universe: Universe {
  get {
    Universe()
  }
}

// RIGHT
var universe: Universe {
  Universe()
}

// RIGHT
var universe: Universe {
  get { multiverseService.current }
  set { multiverseService.current = newValue }
}

(链接) 尽可能使用不透明泛型参数（带有 some）而不是冗长的命名泛型参数语法。

为什么？

不透明泛型参数语法明显不那么冗长，因此比完整的命名泛型参数语法更易读。

// WRONG
func spaceshipDashboard<WarpDriveView: View, CaptainsLogView: View>(
  warpDrive: WarpDriveView,
  captainsLog: CaptainsLogView)
  -> some View
{ … }

func generate<Planets>(_ planets: Planets) where Planets: Collection, Planets.Element == Planet {
  …
}

// RIGHT
func spaceshipDashboard(
  warpDrive: some View,
  captainsLog: some View)
  -> some View
{ … }

func generate(_ planets: some Collection<Planet>) {
  …
}

// Also fine, since there isn't an equivalent opaque parameter syntax for expressing
// that two parameters in the type signature are of the same type:
func terraform<Body: PlanetaryBody>(_ planetaryBody: Body, into terraformedBody: Body) {
  …
}

// Also fine, since the generic parameter name is referenced in the function body so can't be removed:
func terraform<Body: PlanetaryBody>(_ planetaryBody: Body)  {
  planetaryBody.generateAtmosphere(Body.idealAtmosphere)
}

`some Any`

完全不受约束的泛型参数不太常见，但等同于 some Any。例如

func assertFailure<Value>(
  _ result: Result<Value, Error>,
  file: StaticString = #filePath,
  line: UInt = #line)
{
  if case .failure(let error) = result {
    XCTFail(error.localizedDescription, file: file, line: line)
  }
}

// is equivalent to:
func assertFailure(
  _ result: Result<some Any, Error>,
  file: StaticString = #filePath,
  line: UInt = #line)
{
  if case .failure(let error) = result {
    XCTFail(error.localizedDescription, file: file, line: line)
  }
}

some Any 有点不直观，在这种情况下，命名泛型参数对于弥补弱类型信息很有用。因此，最好使用命名泛型参数而不是 some Any。

(链接) 尽量避免使用 @unchecked Sendable。尽可能使用标准的 Sendable 一致性。如果正在使用尚未更新以支持 Swift 并发的模块中的类型，请使用 @preconcurrency import 抑制与并发相关的错误。

@unchecked Sendable 不提供关于类型线程安全性的任何保证，而是不安全地抑制与并发检查相关的编译器错误。

通常有其他更安全的方法来抑制与并发相关的错误

1. 使用 `Sendable` 而不是 `@unchecked Sendable`，如果合适，使用 `@MainActor`

Sendable 一致性是声明类型是线程安全的首选方式。如果符合 Sendable 的类型不是线程安全的，编译器将发出错误。例如，简单的值类型和不可变类总是可以安全地符合 Sendable，但可变类不能。

// RIGHT: Simple value types are thread-safe.
struct Planet: Sendable {
  var mass: Double
}

// RIGHT: Immutable classes are thread-safe.
final class Planet: Sendable {
  let mass: Double
}

// WRONG: Mutable classes are not thread-safe.
final class Planet: Sendable {
  // ERROR: stored property 'mass' of 'Sendable'-conforming class 'Planet' is mutable
  var mass: Double
}

// WRONG: @unchecked is unnecessary because the compiler can prove that the type is thread-safe.
struct Planet: @unchecked Sendable {
  var mass: Double
}

如果将可变类隔离到单个 actor / 线程 / 并发域，则可以使可变类为 Sendable 和线程安全的。可以通过使用诸如 @MainActor 这样的注解（将其隔离到主 actor）将任何可变类设置为 Sendable。

// RIGHT: A mutable class isolated to the main actor is thread-safe.
@MainActor
final class Planet: Sendable {
  var mass: Double
}

// WRONG: @unchecked Sendable is unsafe because mutable classes are not thread-safe.
struct Planet: @unchecked Sendable {
  var mass: Double
}

2. 使用 `@preconcurrency import`

如果正在使用尚未采用 Swift 并发的模块中的非 Sendable 类型，请使用 @preconcurrency import 抑制与并发相关的错误。

/// Defined in `UniverseKit` module
class Planet: PlanetaryBody { 
  var star: Star
}

// WRONG: Unsafely marking a non-thread-safe class as Sendable only to suppress errors
import PlanetaryBody

extension PlanetaryBody: @unchecked Sendable { }

// RIGHT
@preconcurrency import PlanetaryBody

3. 重新组织代码，以便编译器可以验证它是线程安全的

如果可能，重新组织代码，以便编译器可以验证它是线程安全的。这允许您使用 Sendable 一致性，而不是不安全的 @unchecked Sendable 一致性。

在符合 Sendable 时，如果您尝试进行非线程安全的更改，编译器将来会发出错误。使用 @unchecked Sendable 时会失去此保证，这使得意外引入非线程安全的更改变得更容易。

例如，给定这组类

class PlanetaryBody { 
  let mass: Double  
}

class Planet: PlanetaryBody { 
  let star: Star
}

// NOT IDEAL: no compiler-enforced thread safety.
extension PlanetaryBody: @unchecked Sendable { }

编译器无法验证 PlanetaryBody 是否为 Sendable，因为它不是 final。您可以重新组织代码以不使用子类化，而不是使用 @unchecked Sendable

// BETTER: Compiler-enforced thread safety.
protocol PlanetaryBody: Sendable {
  var mass: Double { get }
}

final class Planet: PlanetaryBody, Sendable {
  let mass: Double
  let star: Star
}

在必要时使用 `@unchecked Sendable`

有时确实需要使用 @unchecked Sendable。在这些情况下，您可以添加一个 // swiftlint:disable:next no_unchecked_sendable 注解，其中包含关于我们如何知道该类型是线程安全的，以及为什么我们必须使用 @unchecked Sendable 而不是 Sendable 的解释。

@unchecked Sendable 的规范、安全用例是一个类，其中可变状态受到某些其他线程安全机制（如锁）的保护。此类型是线程安全的，但编译器无法验证这一点。

struct Atomic<Value> {
  /// `value` is thread-safe because it is manually protected by a lock.
  var value: Value { ... }
}

// WRONG: disallowed by linter
extension Atomic: @unchecked Sendable { }

// WRONG: suppressing lint error without an explanation
// swiftlint:disable:next no_unchecked_sendable
extension Atomic: @unchecked Sendable { }

// RIGHT: suppressing the linter with an explanation why the type is thread-safe
// Atomic is thread-safe because its underlying mutable state is protected by a lock.
// swiftlint:disable:next no_unchecked_sendable
extension Atomic: @unchecked Sendable { }

对于在现有用法中是线程安全的但无法重构以支持适当的 Sendable 一致性的类型（例如，由于向后兼容性约束），使用 @unchecked Sendable 也是合理的。

class PlanetaryBody { 
  let mass: Double  
}

class Planet: PlanetaryBody { 
  let star: Star
}

// WRONG: disallowed by linter
extension PlanetaryBody: @unchecked Sendable { }

// WRONG: suppressing lint error without an explanation
// swiftlint:disable:next no_unchecked_sendable
extension PlanetaryBody: @unchecked Sendable { }

// RIGHT: suppressing the linter with an explanation why the type is thread-safe
// PlanetaryBody cannot conform to Sendable because it is non-final and has subclasses.
// PlanetaryBody itself is safely Sendable because it only consists of immutable values.
// All subclasses of PlanetaryBody are also simple immutable values, so are safely Sendable as well.
// swiftlint:disable:next no_unchecked_sendable
extension PlanetaryBody: @unchecked Sendable { }

(链接) 避免定义然后立即返回的属性。 而是直接返回值。

为什么？

立即返回的属性声明通常是多余的且不必要的。有时，这些是作为重构的副产品无意中创建的。自动清理它们可以简化代码。在某些情况下，这也导致 return 关键字本身变得不必要，从而进一步简化了代码。

// WRONG
var spaceship: Spaceship {
  let spaceship = spaceshipBuilder.build(warpDrive: warpDriveBuilder.build())
  return spaceship
}

// RIGHT
var spaceship: Spaceship {
  spaceshipBuilder.build(warpDrive: warpDriveBuilder.build())
}

// WRONG
var spaceship: Spaceship {
  let warpDrive = warpDriveBuilder.build()
  let spaceship = spaceshipBuilder.build(warpDrive: warpDrive)
  return spaceship
}

// RIGHT
var spaceship: Spaceship {
  let warpDrive = warpDriveBuilder.build()
  return spaceshipBuilder.build(warpDrive: warpDrive)
}

(链接) 在比较类型的所有属性时，首选使用生成的 Equatable 实现。 对于结构体，尽可能首选使用编译器合成的 Equatable 实现。

为什么？

手动实现的 Equatable 实现是冗长的，并且保持其最新状态容易出错。例如，在添加新属性时，可能会忘记更新 Equatable 实现以比较它。

/// WRONG: The `static func ==` implementation is redundant and error-prone.
struct Planet: Equatable {
  let mass: Double
  let orbit: OrbitalElements
  let rotation: Double

  static func ==(lhs: Planet, rhs: Planet) -> Bool {
    lhs.mass == rhs.mass
      && lhs.orbit == rhs.orbit
      && lhs.rotation == rhs.rotation
  }
}

/// RIGHT: The `static func ==` implementation is synthesized by the compiler.
struct Planet: Equatable {
  let mass: Double
  let orbit: OrbitalElements
  let rotation: Double
}

/// ALSO RIGHT: The `static func ==` implementation differs from the implementation that 
/// would be synthesized by the compiler and compared all properties, so is not redundant.
struct CelestialBody: Equatable {
  let id: UUID
  let orbit: OrbitalElements

  static func ==(lhs: Planet, rhs: Planet) -> Bool {
    lhs.id == rhs.id
  }
}

在提供 @Equatable 宏的项目中，首选使用该宏来生成类的 static func ==，而不是手动实现它。

/// WRONG: The `static func ==` implementation is verbose and error-prone.
final class Planet: Equatable {
  let mass: Double
  let orbit: OrbitalElements
  let rotation: Double

  static func ==(lhs: Planet, rhs: Planet) -> Bool {
    lhs.mass == rhs.mass
      && lhs.orbit == rhs.orbit
      && lhs.rotation == rhs.rotation
  }
}

/// RIGHT: The `static func ==` implementation is generated by the `@Equatable` macro.
@Equatable
final class struct Planet: Equatable {
  let mass: Double
  let orbit: OrbitalElements
  let rotation: Double
}

(链接) 首选使用 @Entry 宏在 EnvironmentValues 内部定义属性。在向 SwiftUI EnvironemtnValues 添加属性时，尽可能首选使用编译器合成的属性实现。

为什么？

手动实现的环境键是冗长的，并且被认为是遗留模式。考虑到它已向后移植到 iOS 13，@Entry 专门旨在作为替代品。

/// WRONG: The `EnvironmentValues` property depends on `IsSelectedEnvironmentKey`
struct IsSelectedEnvironmentKey: EnvironmentKey {
  static var defaultValue: Bool { false }
}

extension EnvironmentValues {
  var isSelected: Bool {
   get { self[IsSelectedEnvironmentKey.self] }
   set { self[IsSelectedEnvironmentKey.self] = newValue }
  }
}

/// RIGHT: The `EnvironmentValues` property uses the @Entry macro 
extension EnvironmentValues {
  @Entry var isSelected: Bool = false
}

(链接) 避免使用 () 作为类型。优先使用 Void。

// WRONG
let result: Result<(), Error>

// RIGHT
let result: Result<Void, Error>

(链接) 避免使用 Void() 作为 Void 的实例。优先使用 ()。

let completion: (Result<Void, Error>) -> Void 

// WRONG
completion(.success(Void()))

// RIGHT
completion(.success(()))

(链接) 优先使用 count(where: { … }) 而不是 filter { … }.count。
Swift 6.0 (终于!) 在标准库中添加了 count(where:) 方法。优先使用 count(where:) 方法而不是使用 filter(_:) 方法后跟一个 count 调用。
```
// WRONG
let planetsWithMoons = planets.filter { !$0.moons.isEmpty }.count

// RIGHT
let planetsWithMoons = planets.count(where: { !$0.moons.isEmpty })
```

⬆ 返回顶部

文件组织

(链接) 按字母顺序排列并删除文件中的重复模块导入。将所有导入语句放在文件顶部，头注释下方。不要在导入语句之间添加额外的换行符。在第一个导入语句之前和最后一个导入语句之后添加一个空行。

为什么？

标准化的组织方法有助于工程师更快地确定文件依赖哪些模块。
重复的导入语句不起作用，应删除以提高清晰度。

// WRONG

//  Copyright © 2024 Rakuyo. All rights reserved.
//
import DLSPrimitives
import Constellation
import Constellation
import Epoxy

import Foundation

// RIGHT

//  Copyright © 2024 Rakuyo. All rights reserved.
//

import Constellation
import DLSPrimitives
import Epoxy
import Foundation

例外：@testable import 应该分组在常规导入之后，并用空行分隔。

// WRONG

//  Copyright © 2024 Rakuyo. All rights reserved.
//

import DLSPrimitives
@testable import Epoxy
import Foundation
import Nimble
import Quick

// RIGHT

//  Copyright © 2024 Rakuyo. All rights reserved.
//

import DLSPrimitives
import Foundation
import Nimble
import Quick

@testable import Epoxy

(链接) 将连续空格限制为一个空行或空格（不包括缩进）。 优先考虑以下格式指南，而不是不同高度或宽度的空格。

// WRONG
struct Planet {

  let mass:          Double
  let hasAtmosphere: Bool


  func distance(to: Planet) { }

}

// RIGHT
struct Planet {

  let mass: Double
  let hasAtmosphere: Bool

  func distance(to: Planet) { }

}

(链接) 文件应以换行符结尾。

(链接) 包含跨越多行的作用域的声明应与同一作用域中的相邻声明用换行符分隔。 在多行作用域声明（例如类型、扩展、函数、计算属性等）和其他相同缩进级别的声明之间插入一个空行。

为什么？

将作用域声明与同一作用域的其他声明分开，可在视觉上将它们分开，使相邻声明更容易与作用域声明区分开。

// WRONG
struct SolarSystem {
  var numberOfPlanets: Int {
    …
  }
  func distance(to: SolarSystem) -> AstronomicalUnit {
    …
  }
}
struct Galaxy {
  func distance(to: Galaxy) -> AstronomicalUnit {
    …
  }
  func contains(_ solarSystem: SolarSystem) -> Bool {
    …
  }
}

// RIGHT
struct SolarSystem {
  var numberOfPlanets: Int {
    …
  }

  func distance(to: SolarSystem) -> AstronomicalUnit {
    …
  }
}

struct Galaxy {
  func distance(to: Galaxy) -> AstronomicalUnit {
    …
  }

  func contains(_ solarSystem: SolarSystem) -> Bool {
    …
  }
}

(链接) 删除作用域顶部和底部的空行，不包括可以选择包含空行的类型主体。

// WRONG
class Planet {
  func terraform() {

    generateAtmosphere()
    generateOceans()

  }
}

// RIGHT
class Planet {
  func terraform() {
    generateAtmosphere()
    generateOceans()
  }
}

// Also fine!
class Planet {

  func terraform() {
    generateAtmosphere()
    generateOceans()
  }

}

(链接) 每个实现一致性的类型和扩展都应以 MARK 注释开头。
- 类型应以 // MARK: - TypeName 注释开头。
- 添加一致性的扩展应以 // MARK: - TypeName + ProtocolName 注释开头。
- 紧跟在要扩展的类型之后的扩展应省略该类型的名称，而改用 // MARK: ProtocolName。
- 如果文件中只有一个类型或扩展，则可以省略 MARK 注释。
- 如果所讨论的扩展为空（例如，其主体中没有声明），则可以省略 MARK 注释。
- 对于不添加新一致性的扩展，请考虑添加带有描述性注释的 MARK。
```
// MARK: - GalaxyView

final class GalaxyView: UIView { … }

// MARK: ContentConfigurableView

extension GalaxyView: ContentConfigurableView { … }

// MARK: - Galaxy + SpaceThing, NamedObject

extension Galaxy: SpaceThing, NamedObject { … }
```
(链接) 使用 // MARK: 将类型定义和扩展的内容按顺序列到以下各节中。 所有类型定义和扩展都应以这种一致的方式进行划分，以便您的代码读者可以轻松跳转到他们感兴趣的内容。
- // MARK: Lifecycle 用于 init 和 deinit 方法。
- // MARK: Open 用于 open 属性和方法。
- // MARK: Public 用于 public 属性和方法。
- // MARK: Package 用于 package 属性和方法。
- // MARK: Internal 用于 internal 属性和方法。
- // MARK: Fileprivate 用于 fileprivate 属性和方法。
- // MARK: Private 用于 private 属性和方法。
- 如果所讨论的类型是枚举，则其用例应位于第一个 // MARK: 之上。
- 不要将这些部分中的每一部分细分为子部分，因为它会使方法下拉菜单更加混乱，从而降低其效用。相反，按功能对方法进行分组，并使用智能命名来明确哪些方法是相关的。如果存在足够多的方法以至于似乎需要子部分，请考虑将您的代码重构为多种类型。
- 如果类型或扩展的所有定义都属于同一类别（例如，类型或扩展仅包含 internal 属性），则可以省略 // MARK:。
- 如果所讨论的类型是简单值类型（例如，少于 20 行），则可以省略 // MARK:，因为它会损害可读性。

(链接) 在每个顶级部分中，按以下顺序放置内容。 这使您的代码的新读者可以更轻松地找到他们正在寻找的内容。

嵌套类型和类型别名
静态属性
带有主体的静态属性
带有主体的类属性
SwiftUI 动态属性（@State、@Environment、@Binding 等），按类型分组
实例属性
带有主体的实例属性
静态方法
类方法
实例方法

计算属性和带有属性观察器的属性应出现在同一类型声明集的末尾。（例如，实例属性。）

// WRONG
class PlanetView: UIView {

  static var startOfTime { -CGFloat.greatestFiniteMagnitude / 0 }

  var atmosphere: Atmosphere {
     didSet {
       print("oh my god, the atmosphere changed")
     }
   }

  override class var layerClass: AnyClass {
    PlanetLayer.self
  }

  var gravity: CGFloat

  static let speedOfLight: CGFloat = 300_000
}

// RIGHT
class PlanetView: UIView {

  static let speedOfLight: CGFloat = 300_000
  static var startOfTime { -CGFloat.greatestFiniteMagnitude / 0 }

  override class var layerClass: AnyClass {
    PlanetLayer.self
  }

  var gravity: CGFloat
  var atmosphere: Atmosphere {
     didSet {
       print("oh my god, the atmosphere changed")
     }
   }
}

SwiftUI 属性是 SwiftUI 视图中存在的一种特殊类型的属性。这些视图符合 DynamicProperty 协议，并导致视图的主体重新计算。鉴于这种常见的功能和类似的语法，最好将它们分组。

// WRONG

struct CustomSlider: View {

  // MARK: Internal

  var body: some View {
    ...
  }

  // MARK: Private

  @Binding private var value: Value
  private let range: ClosedRange<Double>
  @Environment(\.sliderStyle) private var style
  private let step: Double.Stride
  @Environment(\.layoutDirection) private var layoutDirection
}

// RIGHT

struct CustomSlider: View {
  
  // MARK: Internal

  var body: some View {
    ...
  }

  // MARK: Private

  @Environment(\.sliderStyle) private var style
  @Environment(\.layoutDirection) private var layoutDirection
  @Binding private var value: Value

  private let range: ClosedRange<Double>
  private let step: Double.Stride
}

此外，在 SwiftUI 属性的分组中，最好也按其动态属性类型对属性进行分组。格式化程序应用的分组顺序由类型第一次出现时决定

// WRONG
struct CustomSlider: View {

  @Binding private var value: Value
  @State private var foo = Foo()
  @Environment(\.sliderStyle) private var style
  @State private var bar = Bar()
  @Environment(\.layoutDirection) private var layoutDirection

  private let range: ClosedRange<Double>
  private let step: Double.Stride
}

// RIGHT
struct CustomSlider: View {

  @Binding private var value: Value
  @State private var foo = Foo()
  @State private var bar = Bar()
  @Environment(\.sliderStyle) private var style
  @Environment(\.layoutDirection) private var layoutDirection

  private let range: ClosedRange<Double>
  private let step: Double.Stride
}

(链接) 在不同种类的属性声明之间添加空行。（例如，静态属性和实例属性之间。）

// WRONG
static let gravityEarth: CGFloat = 9.8
static let gravityMoon: CGFloat = 1.6
var gravity: CGFloat

// RIGHT
static let gravityEarth: CGFloat = 9.8
static let gravityMoon: CGFloat = 1.6

var gravity: CGFloat

(链接) 删除未使用的 private 和 fileprivate 属性、函数和类型别名

为什么？

提高可读性，因为代码无效，应删除以提高清晰度。

// WRONG: Includes private declarations that are unused
struct Planet {
  var ageInBillionYears: Double {
    ageInMillionYears / 1000
  }
  
  private var ageInMillionsOfYears: Double
  private typealias Dependencies = UniverseBuilderProviding // unused
  private var mass: Double // unused
  private func distance(to: Planet) { } // unused
}
  
// RIGHT
struct Planet {
  var ageInBillionsOfYears: Double {
    ageInMillionYears / 1000
  }

  private var ageInMillionYears: Double
}

(链接) 删除未定义任何属性、函数或一致性的空扩展。

为什么？

提高可读性，因为代码无效，应删除以提高清晰度。

// WRONG: The first extension is empty and redundant.
extension Planet {}

extension Planet: Equatable {}

// RIGHT: Empty extensions that add a protocol conformance aren't redundant.
extension Planet: Equatable {}

⬆ 返回顶部

Objective-C 互操作性

(链接) 优先使用纯 Swift 类，而不是 NSObject 的子类。 如果你的代码需要被某些 Objective-C 代码使用，将其封装起来以暴露所需的功能。根据需要，在单独的方法和变量上使用 @objc，而不是通过 @objcMembers 将一个类的所有 API 都暴露给 Objective-C。

class PriceBreakdownViewController {

  private let acceptButton = UIButton()

  private func setUpAcceptButton() {
    acceptButton.addTarget(
      self,
      action: #selector(didTapAcceptButton),
      forControlEvents: .touchUpInside)
  }

  @objc
  private func didTapAcceptButton() {
    // ...
  }
}

⬆ 返回顶部

修订

我们鼓励您 Fork 这个指南，并根据您团队的风格指南更改规则。您可以在下面列出对风格指南的一些修改。这使您可以定期更新您的风格指南，而无需处理合并冲突。

⬆ 返回顶部

Rakuyo Swift 风格指南

目标

指导原则

asdf/mise 插件

Swift Package Manager 命令插件

目录

Xcode 格式化

为什么？

命名

为什么？

为什么？

风格

为什么？

为什么？

为什么？

为什么？

为什么？

为什么？

为什么？

例子

为什么？

例子

为什么？

函数

为什么？

为什么？

闭包

为什么？

运算符

例子

模式

为什么？

为什么？

为什么？

为什么？

为什么？

为什么？

为什么？

为什么？

为什么？

为什么？

为什么？

为什么？

为什么？

为什么？

为什么？

some Any

1. 使用 Sendable 而不是 @unchecked Sendable，如果合适，使用 @MainActor

2. 使用 @preconcurrency import

3. 重新组织代码，以便编译器可以验证它是线程安全的

在必要时使用 @unchecked Sendable

为什么？

为什么？

为什么？

文件组织

为什么？

为什么？

为什么？

为什么？

Objective-C 互操作性

修订

`some Any`

1. 使用 `Sendable` 而不是 `@unchecked Sendable`，如果合适，使用 `@MainActor`

2. 使用 `@preconcurrency import`

在必要时使用 `@unchecked Sendable`