swift-format 全配置解析：每个选项到底改变了什么

lineLength#

一行最多多少个字符。超过就触发换行策略。

1
// lineLength: 80
2
let view = makeRow(title: "Title", subtitle: "Subtitle", icon: iconName, action: handler)
3
let view = makeRow(
4
  title: "Title", subtitle: "Subtitle", icon: iconName, action: handler)

我的选择：100（默认值）。 Swift 的类型名和参数标签本来就长，80 会让 SwiftUI 的 view 代码碎成一片。100 是 Google Swift Style Guide 的值，也是 swift-format 的默认值。

indentation#

一级缩进用什么。可以写 {"spaces": N} 或 {"tabs": N}。

1
struct Point {
2
  var x: Int
3
  func move() {
4
    x += 1
5
  }
6
    var x: Int
7
    func move() {
8
        x += 1
9
    }
10
}

我的选择：{"spaces": 4}。 swift-format 默认 2 空格，但 Xcode 的默认编辑器设置是 4 空格，Apple 自家的示例代码也是 4。我不想让「Xcode 里手敲的缩进」和「格式化后的缩进」不一致。

tabWidth#

这个选项的名字有误导性。它不是”缩进宽度”，而是一个 tab 字符在计算行长时算几列。

如果 indentation 用的是空格，这个值完全不影响输出。只有用 tab 缩进时才有区别 —— 下面两段是同一份代码、同样的 lineLength: 60、同样的 tab 缩进，只差 tabWidth：

1
// tabWidth: 8 —— 两层 tab 被算作 16 列，剩余空间不够，于是换行
2
func outer() {
3
  func inner() {
4
    let r = compute(
5
      alpha: 1, beta: 2, gamma: 3,
6
      delta: 44)
7
  }
8
}
9

10
// tabWidth: 4 —— 两层 tab 只算 8 列，一行放得下
11
func outer() {
12
  func inner() {
13
    let r = compute(alpha: 1, beta: 2, gamma: 3, delta: 44)
14
  }
15
}

我的选择：4，但说实话这一条在我的配置里不起作用。 因为我用空格缩进，swift-format 根本不会遇到需要折算宽度的 tab。我留着它只是为了和编辑器设置保持一致，不留也一样。

indentBlankLines#

空行要不要补上当前层级的缩进（也就是留下一串尾随空格）。

1
func f() {
2
    let a = 1
3

4
    ⎵⎵⎵⎵
5
    let b = 2
6
}

（上面的 ⎵ 是实际产生的空格。）

我的选择：false（默认值）。 打开它会制造尾随空白，和大多数编辑器的「保存时删除行尾空格」以及 git diff 的习惯冲突。

maximumBlankLines#

允许连续几个空行，多的折叠掉。

1
let a = 1
2

3

4
let b = 2

（上面是 2 改回默认 1 的效果。）

我的选择：1（默认值）。 我用空行分隔逻辑块，但不需要两行以上的间隔来表示”更大的分隔”——那是标题注释该干的事。

spacesBeforeEndOfLineComments#

行尾 // 注释前面留几个空格。

1
let a = 1  // one
2
let bb = 22  // two
3
let a = 1 // one
4
let bb = 22 // two

（上面是改成 1 的效果。）注意它不做对齐，只保证固定数量的空格。

我的选择：2（默认值）。 一个空格时注释和代码贴得太近，两个空格视觉上能分开。

spacesAroundRangeFormationOperators#

... 和 ..< 两边加不加空格。

1
let r = 0..<10
2
let c = 1...5
3
let r = 0 ..< 10
4
let c = 1 ... 5

我的选择：false（默认值）。 0..<10 我读成一个整体，加空格反而像三个独立的词。

indentConditionalCompilationBlocks#

#if / #endif 里面的代码要不要多缩进一层。

1
func f() {
2
  #if DEBUG
3
  let a = 1
4
  print(a)
5
    let a = 1
6
    print(a)
7
  #endif
8
}

（默认 true 就是右边的样子。）

我的选择：true（默认值）。 #if 是一个有开有合的结构，内容缩进一层符合直觉。

indentSwitchCaseLabels#

case 要不要相对 switch 缩进。

1
switch v {
2
case 1:
3
  print(1)
4
default:
5
  break
6
  case 1:
7
    print(1)
8
  default:
9
    break
10
}

我的选择：false（默认值）。 这是 Swift 社区的主流写法，Apple 文档也是这么排的。打开之后 switch 会整体往右推两层，在已经嵌套的代码里很占地方。

respectsExistingLineBreaks#

要不要尊重你已经手写的换行。

1
let a = compute(
2
  x: 1,
3
  y: 2
4
)
5
let a = compute(x: 1, y: 2)
6
let b = 1 + 2

（上面是改成 false 的效果：所有能合并的都合并。）

我的选择：true（默认值）。 这是我认为最重要的一条。关掉它，swift-format 会变成一个「最大化行密度」的机器，你为了表达分组而手动拆开的参数列表会被无情合并。打开它，手写的换行只要不违反规则就保留 —— 格式化工具负责下限，人负责表达。

lineBreakBeforeEachArgument#

当参数列表一行放不下时：是尽量塞满每一行，还是每个参数单独一行。

1
let view = makeRow(
2
  title: "Title", subtitle: "Subtitle", icon: iconName, action: handler, isEnabled: true)
3
  title: "Title",
4
  subtitle: "Subtitle",
5
  icon: iconName,
6
  action: handler,
7
  isEnabled: true
8
)

函数声明也一样：

1
func makeRow(
2
  title: String, subtitle: String, iconName: String, action: @escaping () -> Void, isEnabled: Bool,
3
  title: String,
4
  subtitle: String,
5
  iconName: String,
6
  action: @escaping () -> Void,
7
  isEnabled: Bool,
8
  badgeCount: Int
9
) -> Row {

我的选择：true。 默认的塞满式换行有个实际问题：加一个参数会让后面所有参数重新排列，diff 里看起来像改了五行，其实只加了一个。一参数一行之后，加参数就是加一行。SwiftUI 的初始化器参数又多又长，这个差别在 code review 里很明显。

代价是竖向行数变多。我接受。

lineBreakBeforeEachGenericRequirement#

同一件事，作用在 where 子句上。

1
func merge<A, B>(_ a: A, _ b: B) -> [A.Element]
2
where
3
  A: Sequence, B: Sequence, A.Element == B.Element, A.Element: Hashable, B.Element: Comparable,
4
  A: Codable, B: Codable, A: Sendable
5
  A: Sequence,
6
  B: Sequence,
7
  A.Element == B.Element,
8
  A.Element: Hashable,
9
  B.Element: Comparable,
10
  A: Codable,
11
  B: Codable,
12
  A: Sendable
13
{

注意：只有 where 子句长到放不下时才会触发，短的不受影响。

我的选择：true。 和上一条同一个理由，保持一致。实际上我的项目里还没有长到需要换行的 where 子句，这一条目前是写给未来的。

lineBreakBeforeControlFlowKeywords#

else / catch 这类关键字要不要另起一行。

1
  if condition {
2
    print(a)
3
  } else {
4
  }
5
  else {
6
    print(0)
7
  }
8
}

我的选择：false（默认值）。 } else { 是 Swift 的通用写法，改成 Allman 风格会让代码在任何 Swift 项目里都显得突兀。

lineBreakBetweenDeclarationAttributes#

多个属性要不要各占一行。

1
@MainActor @preconcurrency final class Store {
2
@MainActor
3
@preconcurrency
4
final class Store {
5
  var value = 0
6
}

我的选择：false（默认值）。 SwiftUI 里 @State private var 这种组合太常见了，强制拆行会让属性声明区域变成一片竖条。而且这个选项是全局的，没法只对「长属性」生效。

lineBreakAroundMultilineExpressionChainComponents#

链式调用放不下时，是在方法名之间断开，还是在参数括号里断开。

1
let names = people.filter { $0.age > 18 }.map { $0.name.uppercased() }.sorted().joined(
2
  separator: ", ")
3
let names = people.filter { $0.age > 18 }.map { $0.name.uppercased() }.sorted()
4
  .joined(separator: ", ")

我的选择：false（默认值）。 这条我犹豫过。打开之后链式调用的断点更符合语义（在 . 处断），但它的行为是「强制在多行链的每个组件前后换行」，一旦某条链被判定为多行，整条链都会散开。默认值的输出在我的代码里够用，暂时不动。

prioritizeKeepingFunctionOutputTogether#

函数签名放不下时，优先保住哪部分。这是本文里我最喜欢的一条。

1
func loadConfiguration(from url: URL, using decoder: JSONDecoder, strict: Bool) throws
2
  -> Configuration
3
{
4
func loadConfiguration(
5
  from url: URL, using decoder: JSONDecoder, strict: Bool
6
) throws -> Configuration {
7
  try decoder.decode(Configuration.self, from: Data(contentsOf: url))
8
}

默认值（false）会把返回类型甩到下一行，然后因为签名跨行，左花括号也被迫单独占一行 —— 结果是三行签名加一个孤零零的 {。打开之后，参数列表被拆开，但 ) throws -> Configuration { 保持在一起。

我的选择：true。 返回类型是函数签名里信息量最大的部分之一，把它和参数列表切散没有道理。另外那个孤立的 { 在一堆 4 空格缩进的代码里特别扎眼。

multiElementCollectionTrailingCommas#

多元素的数组/字典字面量，最后一个元素后面加不加逗号。

1
let colors = [
2
  "red",
3
  "green",
4
  "blue"
5
  "blue",
6
]

单元素的集合不受影响 —— ["only"] 拆成多行时不会加逗号。

我的选择：true（默认值），但它在我的配置里已经不起作用了。 原因见下一条。

multilineTrailingCommaBehavior#

作用范围更大：参数列表、元组等所有「对称分隔的逗号列表」，也包括集合字面量。三个取值：

• keptAsWritten（默认）：你写了就保留，没写就不加，集合字面量交给上一个选项处理
• alwaysUsed：多行列表一律补上
• neverUsed：一律删掉

1
let view = makeRow(
2
  title: "Title",
3
  subtitle: "Subtitle",
4
  icon: iconName,
5
  icon: iconName
6
)

我的选择：neverUsed。

我一开始设的是 alwaysUsed。理由是尾随逗号能让最后一个元素和其他元素一样容易增删、重排，加一个参数只动一行 diff。这个理由本身没错，但它有个覆盖不到的地方：multilineTrailingCommaBehavior 顾名思义只管多行列表。单行的 makeRow(title: "a", subtitle: "b") 永远不会被加上逗号。

于是 alwaysUsed 实际得到的是「多行有、单行没有」的分裂规则——同一个调用，因为长度跨过 100 列就换一种写法。neverUsed 则是一条规则管所有情况：任何地方都没有尾随逗号。我后来换成了后者。

代价是放弃了 diff 上的那点好处。换来的是不用再去想「这个列表现在是单行还是多行」。

两个连带影响。

一是 neverUsed 会覆盖 multiElementCollectionTrailingCommas。即使后者仍然是 true，集合字面量的尾随逗号照样被删掉：

1
// multiElementCollectionTrailingCommas: true + multilineTrailingCommaBehavior: neverUsed
2
let colors = [
3
    "red",
4
    "green",
5
    "blue"
6
]

也就是说 multiElementCollectionTrailingCommas 这一行在我的配置里现在是空转的。留着是为了将来改回 keptAsWritten 时不用重新想，但它确实不影响任何输出。

二是编译器版本要求消失了。参数列表里的尾随逗号是 SE-0439 引入的语法，需要 Swift 6.1 及以上的编译器（我实测过，它不受语言模式限制，用 -swift-version 5 也能编译，只要编译器够新）。选 alwaysUsed 意味着产出的代码在旧工具链上编译不过；选 neverUsed 就没有这个问题。

顺便一个 bug。 手写的单行尾随逗号语法上是合法的（makeRow(title: "a", subtitle: "b",) 和 [1, 2, 3,] 都能编译），但 swift-format 处理得不干净。neverUsed 删掉逗号后会留下一个空格，要跑第二遍才收敛：

1
// 输入
2
let v = makeRow(title: "a", subtitle: "b",)
3

4
// 第一遍
5
let v = makeRow(title: "a", subtitle: "b" )
6

7
// 第二遍
8
let v = makeRow(title: "a", subtitle: "b")

默认的 keptAsWritten 更糟：它把 ("b", ) 原样留着，跑多少遍都不变。集合字面量没有这个问题。实际写代码时不太会手打单行尾随逗号，但如果你是从别的项目迁移过来的，值得跑两遍格式化再提交。

reflowMultilineStringLiterals#

多行字符串字面量里，超长的行要不要用 \ 续行重排。

1
// never（默认）
2
let message = """
3
  This line is short.
4
  This particular line is quite long and definitely goes past the configured maximum line length limit of one hundred columns.
5
  """
6

7
// onlyLinesOverLength
8
let message = """
9
  This line is short.
10
  This particular line is quite long and definitely goes past the configured maximum line length \
11
  limit of one hundred columns.
12
  """

第三个取值 always 的文档说明是「总是重排，忽略已有的转义换行」。在我试过的几个例子里，它和 onlyLinesOverLength 的输出一致 —— 它不会把短行合并起来。区别应该只在已经含有 \ 续行的字面量上。

我的选择：onlyLinesOverLength。 我不希望字符串字面量成为唯一能突破 100 列的地方（那会让 lineLength 形同虚设），但也不想让格式化工具去动那些我按行写好的短文本。这个中间值刚好。

fileScopedDeclarationPrivacy#

文件级的私有声明统一用 private 还是 fileprivate。对应 FileScopedDeclarationPrivacy 规则。

1
fileprivate let cache = 1
2
fileprivate func helper() {}
3
private let cache = 1
4
private func helper() {}

在文件作用域，这两个关键字的语义完全相同，所以这纯粹是统一写法。

我的选择：private（默认值）。 短，而且和类型内部的 private 视觉一致。

noAssignmentInExpressions#

NoAssignmentInExpressions 规则的白名单：哪些函数允许在参数里写赋值。

默认值是 ["XCTAssertNoThrow"]，因为 XCTAssertNoThrow(x = try compute()) 是测试里的常见写法。清空白名单后，这一行就会被报告：

1
warning: [NoAssignmentInExpressions] move this assignment expression into its own statement

我的选择：保持默认的 ["XCTAssertNoThrow"]。 我的项目用 Swift Testing 而不是 XCTest，所以这个白名单目前是空转的。留着默认值没有成本。

orderedImports#

OrderedImports 规则的两个开关。

shouldGroupImports（默认 true）：把不同种类的 import 分组，中间空一行。

1
import Foundation
2
import UIKit
3

4
import enum Swift.Optional
5

6
@testable import MyApp
7
import UIKit

顺序是：普通 import → 单个符号的 import（import enum Swift.Optional）→ @testable import，组内按字母序。关掉之后全部混在一起，只按字母序排。

includeConditionalImports（默认 false）：#if 块里的 import 要不要也排序。

1
#if canImport(Combine)
2
  import Combine
3
  import Accelerate
4
  import Combine
5
#endif

我的选择：两个都保持默认（分组 = true，条件编译 = false）。 分组让 @testable 一眼可见。条件编译块里的 import 顺序有时候是有意义的（比如依赖关系），我不想让工具去动它。

AlwaysUseLiteralForEmptyCollectionInit（会改写）#

1
var names = [String]()
2
var lookup = [String: Int]()
3
var names: [String] = []
4
var lookup: [String: Int] = [:]

为什么开： 两种写法等价，但后者把类型写在类型的位置上。类型标注在声明的左边，值在右边，这和 var x: Int = 0 的形状一致。

BeginDocumentationCommentWithOneLineSummary（只报告）#

要求文档注释的第一句是独立的一行摘要。

1
/// Returns the sum of two integers. This function is very simple. It adds them.
2
func add(_ a: Int, _ b: Int) -> Int { a + b }

1
warning: [BeginDocumentationCommentWithOneLineSummary]
2
add a blank comment line after this sentence: "Returns the sum of two integers."

为什么开： Xcode 的 Quick Help 和 DocC 都只取第一段作为摘要。摘要写成三句话，快速查看里就会看到一大坨。

NeverForceUnwrap / NeverUseForceTry / NeverUseImplicitlyUnwrappedOptionals（都只报告）#

1
warning: [NeverForceUnwrap] do not force unwrap 'Int(s!)'
2
warning: [NeverUseForceTry] do not use force try
3
warning: [NeverUseImplicitlyUnwrappedOptionals] use 'String' or 'String?' instead of 'String!'

为什么开： Atofolio 是个导入外部数据的归档应用 —— Bangumi、Steam、Apple Music 的字段随时可能缺失或变形。项目的第一原则是「不编造缺失的信息，未知就保持未知」。! 是和这条原则最直接冲突的语法：它把「这里可能没有值」变成「这里没有值就崩溃」。

这三条只在 lint 下报告，不会改写代码 —— 也不该改写，因为正确的修法（guard let、do/catch、改类型）取决于上下文。

代价是会有一些无法避免的报告。UIKit 的 @IBOutlet 按设计就是隐式解包的，Bundle.main.url(forResource:) 这类「资源一定在 app 包里」的调用也很难不写 !。这种时候用一行注释单点豁免：

1
// swift-format-ignore: NeverUseImplicitlyUnwrappedOptionals
2
var label: String!

这条指令只对紧随其后的那个声明生效，后面的声明照常检查。整个文件豁免用 // swift-format-ignore-file。

NoEmptyLinesOpeningClosingBraces（会改写）#

1
struct S {
2

3
  var x = 1
4

5
}

为什么开： 紧贴花括号的空行不表达任何分组，只是敲回车时留下的痕迹。

OmitExplicitReturns（会改写）#

1
func double(_ x: Int) -> Int {
2
  return x * 2
3
  x * 2
4
}
5
var squared: Int {
6
  return 4
7
  4
8
}

为什么开： SwiftUI 的 body 和大量计算属性都是单表达式。既然语言已经允许省略，就让工具统一省掉，而不是让每个人凭习惯决定。配合下面这条默认规则 UseSingleLinePropertyGetter（它会去掉多余的 get { }），计算属性能一路简化到只剩表达式本身。

这条我保留一点怀疑：省掉 return 之后，单表达式函数和闭包在视觉上更难区分。但在 SwiftUI 代码里收益更大。

UseEarlyExits（会改写）#

1
func f(_ x: Int?) {
2
  if let x = x {
3
    print(x)
4
  } else {
5
  guard let x = x else {
6
    return
7
  }
8
  print(x)
9
  print("done")
10
}

为什么开： guard 把「不满足条件就退出」的意图写在前面，主逻辑留在最外层缩进。这是 Swift 里少见的、工具能可靠自动完成的语义级改写。

注意它只处理 else 分支只有一个退出语句的情况，不会乱动复杂分支。

UseWhereClausesInForLoops（会改写）#

1
func f(_ xs: [Int]) {
2
  for x in xs {
3
    if x > 0 {
4
      print(x)
5
    }
6
  for x in xs where x > 0 {
7
    print(x)
8
  }
9
}

为什么开： 少一层缩进，而且 where 把「筛选」和「处理」在语法上分开了。

ValidateDocumentationComments（只报告）#

检查文档注释的参数列表和实际签名是否一致。

1
/// Returns the sum.
2
///
3
/// - Parameters:
4
///   - a: first
5
///   - c: wrong name
6
/// - Returns: the sum
7
func add(a: Int, b: Int) -> Int { a + b }

1
warning: [ValidateDocumentationComments]
2
change the parameters of the documentation of 'add' to match its parameters

为什么开： 文档注释和签名不同步是最难发现的一类错误，因为它不影响编译也不影响运行，只会误导下一个读代码的人（通常是我自己）。

自动改写类#

DoNotUseSemicolons —— 分号换成换行。

1
let a = 1; let b = 2;
2
let a = 1
3
let b = 2

FullyIndirectEnum —— 所有 case 都 indirect 时，提升到 enum 上。

1
enum Tree {
2
  indirect case node(Tree, Tree)
3
  indirect case leaf(Tree)
4
indirect enum Tree {
5
  case node(Tree, Tree)
6
  case leaf(Tree)
7
}

GroupNumericLiterals —— 长数字字面量加下划线分组。

1
let big = 1000000
2
let hex = 0xFFFFFFFF
3
let big = 1_000_000
4
let hex = 0xFFFF_FFFF
5
let bin = 0b11110000

注意最后一行没被改：8 位的二进制字面量在阈值内。

NoAccessLevelOnExtensionDeclaration —— 访问级别从 extension 移到成员上。

1
public extension String {
2
  func shout() -> String { uppercased() }
3
extension String {
4
  public func shout() -> String { uppercased() }
5
}

NoAssignmentInExpressions —— 把表达式里的赋值拆成独立语句。

1
func f() -> Int {
2
  var x = 0
3
  return x = 5
4
  x = 5
5
  return
6
}

（这个例子里的原始代码本来就可疑，改写结果也不一定能编译。这条规则的价值在于它逼你去看那一行。）

NoCasesWithOnlyFallthrough —— 合并只有 fallthrough 的 case。

1
case 1:
2
  fallthrough
3
case 2:
4
case 1, 2:
5
  print("small")

NoEmptyTrailingClosureParentheses —— 尾随闭包前的空括号。

1
UIView.animate() {
2
UIView.animate {

NoLabelsInCasePatterns —— case 模式里多余的标签。

1
case .a(x: let x, y: let y):
2
case .a(let x, let y):

NoParensAroundConditions —— 条件外面的括号。

1
if (x > 0) {
2
if x > 0 {
3
while (x < 10) { break }
4
while x < 10 { break }

NoVoidReturnOnFunctionSignature —— 函数签名上显式的 -> Void。

1
func f() -> Void {}
2
func g() -> () {}
3
func f() {}
4
func g() {}

ReturnVoidInsteadOfEmptyTuple —— 闭包类型里的 () 换成 Void。

1
let handler: (Int) -> () = { _ in }
2
let handler: (Int) -> Void = { _ in }

和上一条方向相反，但不矛盾：函数签名上的返回类型直接删掉，类型标注里的则写成 Void。

OneCasePerLine —— 带关联值或原始值的 case 单独成行。

1
enum E {
2
  case a, b, c(Int)
3
  case d = 1, e = 2
4
  case a, b
5
  case c(Int)
6
  case d = 1
7
  case e = 2
8
}

注意不带值的 case a, b 被保留在一行。

OneVariableDeclarationPerLine —— 一行一个变量。

1
let a = 1, b = 2, c = 3
2
let a = 1
3
let b = 2
4
let c = 3

UseExplicitNilCheckInConditions —— 丢弃绑定值的 if let _ 换成 nil 比较。

1
if let _ = x {
2
if x != nil {

UseLetInEveryBoundCaseVariable —— case let .a(x, y) 换成每个绑定都写 let。

1
case let .a(x, y):
2
case .a(let x, let y):

UseShorthandTypeNames —— 泛型写法换成简写。

1
var a: Array<Int> = []
2
var b: Optional<String> = nil
3
var c: Dictionary<String, Int> = [:]
4
var a: [Int] = []
5
var b: String? = nil
6
var c: [String: Int] = [:]

UseSingleLinePropertyGetter —— 只读属性里多余的 get { }。

1
var x: Int {
2
  get {
3
    return 1
4
  }
5
  return 1
6
}

UseTripleSlashForDocumentationComments —— 块注释文档换成 ///。

1
/**
2
 * A documented function.
3
 */
4
/// A documented function.
5
func f() {}

FileScopedDeclarationPrivacy 和 OrderedImports 前面已经讲过（它们各自有配置项）。

只报告类#

这些规则不会改代码，只在 lint 下报告。

这一组我没有特别的意见，它们报告的都是实打实的问题。唯一想提一句的是 ReplaceForEachWithForLoop：forEach 里不能用 break/continue，return 的语义也和直觉不同（它只退出当前一次闭包调用），换成 for-in 确实更安全。