Swift团队的官方GitHub组织swiftlang下维护着一系列重要仓库，其中除了编译器本身，还有一份被广泛引用的API设计指南。这份指南虽然主要面向标准库和框架作者，但其背后的设计思想同样适用于日常业务代码。很多团队在制定Swift编码规范时，会直接照搬Objective-C时代的旧习惯，结果写出来的代码既不符合Swift的语言特性，也难以通过静态检查工具的约束。本文把Swift代码规范中最常见的几个问题集中梳理一遍，结合官方建议给出结论和示例。
命名规范：驼峰、清晰性和不要缩写
Swift官方指南在命名上的核心原则只有一条：清晰优先于简洁。变量、函数、类型一律使用大小写驼峰命名，类型和协议用大驼峰（如NetworkManager），变量和函数用小驼峰（如fetchUserProfile）。Swift里基本不存在下划线前缀的习惯，这一点和Objective-C的ibOutlet风格完全不同，从OC迁移过来的团队尤其要注意。
命名时还要避免缩写。像usrNm这种写法在Swift里是不被接受的，应该写成userName。但一些已经成为行业通用词汇的缩写是允许的，比如URL、ID、JSON。另外一个容易忽略的细节是方法命名的副作用表达：如果方法会修改对象自身，官方建议用动词原型，比如reverse()；如果返回一个新值而不修改自身，则用过去分词或-ed形式，比如reversed()。标准库里这种对比随处可见。
// 修改自身，动词原型 mutating func reverse() // 返回新值，不修改自身，ed形式 func reversed() -> [Element] // 返回布尔值的方法，通常以 is / has 等开头 func isEmpty -> Bool func contains(_ element: Element) -> Bool
还有一个高频争议点是函数参数标签。Swift允许参数名和标签分离，规范的做法是让调用处读起来像自然语言，例如move(from: start, to: end)就比move(start, end)清晰得多。如果标签会带来冗余，可以显式用下划线省略，例如min(x, y)这种数学运算式调用。
注释与文档：写给人看的优先
官方指南明确说，注释的第一读者是第一次接触这段代码的人。Swift提供了Markdown语法的文档注释，用三个斜杠开头，Xcode的快捷提示会直接渲染这些内容。规范上建议公共API必须写文档注释，私有实现可以只在逻辑复杂处补充说明，而不是机械地给每一行代码加注释。
文档注释有几个约定俗成的标记：- Parameter描述参数，- Returns描述返回值，- Throws声明抛出的错误。这些标记不仅给人看，Xcode也能识别并在提示框中格式化显示。注释的内容要说明“为什么”而不是重复代码已经表达的“是什么”，一行i += 1 // i加一这种注释是负资产。
/// 从缓存中加载用户资料。 /// /// 如果缓存未命中，会发起一次网络请求并回写缓存。 /// - Parameter userID: 用户的唯一标识 /// - Returns: 解析后的用户资料 /// - Throws: `NetworkError.timeout` 当请求超过30秒时抛出 func loadProfile(userID: String) throws -> UserProfile
对于标记为弃用的API，务必使用@available(*, deprecated, message:)属性并在message里写清替代方案，这比单纯删掉方法友好得多，调用方编译时就能看到提示。
访问控制与结构组织
Swift提供了private、fileprivate、internal、public、open五级访问控制。常见的规范建议是默认使用最严格的级别，从private开始，确实需要暴露时再逐级放宽。open只应该出现在设计上明确允许子类重写的框架API中，业务代码里滥用open会让继承关系失控。
文件组织上，一个文件包含一个主类型是普遍共识，类型相关的私有辅助类型可以放在同一文件。代码顺序推荐：属性声明、初始化方法、生命周期方法、公共方法、私有方法。Swift扩展是组织代码的好工具，把协议实现单独放到extension中，可读性会显著提升，也比把几百行代码塞进一个类体里干净得多。
final class OrderListViewController: UIViewController {
// MARK: - 属性
private let tableView = UITableView()
private var orders: [Order] = []
// MARK: - 生命周期
override func viewDidLoad() {
super.viewDidLoad()
setupUI()
}
// MARK: - 私有方法
private func setupUI() {
// 界面搭建逻辑
}
}
// MARK: - UITableViewDataSource
extension OrderListViewController: UITableViewDataSource {
func tableView(_ tableView: UITableView,
numberOfRowsInSection section: Int) -> Int {
orders.count
}
}用MARK做分段注释也是值得保留的习惯，Xcode的跳转栏会识别它，配合// MARK: -的横线分隔，大文件也能快速定位。
自动化工具：SwiftLint与SwiftFormat怎么选
规范写得再好，没有工具强制执行就是一纸空文。Swift生态里两个主流工具分工不同：SwiftLint负责规则检查和强制约束，比如类型名称必须大驼峰、单行长度超限报警告；SwiftFormat负责纯格式化，比如缩进、空格、换行。很多团队是两个都用，格式交给SwiftFormat，规则交给SwiftLint。
SwiftLint通过项目根目录下的.swiftlint.yml配置，可以自定义禁用某些不符合团队习惯的规则。下面是一个常见配置示例，禁用了相对宽松团队觉得过严的line_length，并排除第三方目录。
included:
- Sources
excluded:
- Pods
- Carthage
line_length:
warning: 140
error: 200
identifier_name:
min_length:
warning: 1
disabled_rules:
- trailing_whitespace
opt_in_rules:
- empty_count
- closure_spacing更进一步的做法是把SwiftLint挂到Xcode的Build Phase里，让不合规的代码直接编译失败或在CI上标红。规范落地的关键不是文档写得多详细，而是让工具代替人去记忆规则，代码评审时只讨论设计问题，不再争论缩进和命名。
并发与Swift 6时代的规范变化
Swift 6引入了严格的并发检查，数据竞争在编译期就能被捕获。新的规范要求明确标注哪些代码运行在哪个执行环境：@MainActor标记必须在主线程执行的类型，Sendable协议标记可以安全跨并发域传递的值。旧代码里随意用全局可变变量的写法在新模型下会直接报错。
@MainActor
final class ProfileViewModel: ObservableObject {
@Published private(set) var profile: UserProfile?
func loadProfile() async throws {
profile = try await service.fetchProfile()
}
}
// Sendable 结构体可以安全地在并发域之间传递
struct UserProfile: Sendable, Codable {
let id: String
let name: String
}团队规范里应该尽早把并发标注纳入要求：UI相关类型统一加@MainActor，跨任务传递的数据模型实现Sendable，网络回调用async/await替代completion handler式的嵌套闭包。这些约束在迁移期会增加一些改动量，但换来的是编译器级别的线程安全保证。
总结一下，Swift代码规范的落地路径大致是：命名和注释遵循官方API设计指南，结构组织靠团队约定加MARK分段，执行层面交给SwiftLint和SwiftFormat自动化，再逐步跟进并发模型的新要求。规范本身不是目的，让代码在多人协作中保持一致、让编译器和工具替人把关，才是这套规范真正的价值。