jww-swift-style

JWW Swift 风格

首要规则：生成的代码应看起来像是原本就属于正在修改的代码附近。 最近的周边 Swift 源码和适用的 AGENTS.md 是最终依据。以下内容仅作为周边代码未明确说明时的默认规则——主要适用于新的顶层文件。

输入与输出

• 输入目标 Swift 文件或差异、附近可供参照的源文件，以及所有适用的 AGENTS.md。
• 生成符合本地惯例的最小 Swift 修改或风格审查。进行修改时，说明执行了哪些验证。

编写之前

1. 阅读目标文件和附近可供参照的文件，并阅读每个适用的嵌套 AGENTS.md。
2. 保留现有结构、导入顺序、访问控制风格以及所有 MARK 和分节分隔符。不要进行无关的格式调整或风格清理。
3. 选择适用于目标平台和模块的 API。除非需要使用范围较窄的平台条件编译，否则应确保共享代码与模块支持的所有平台兼容。

源码布局

• 使用 4 个空格缩进，并通过空行对声明和逻辑步骤分组。
• 行长度限制遵循适用的 SwiftLint line_length 设置；未配置时，默认上限为 150 个字符。遵循仓库的明确覆盖设置，包括禁用 line_length 规则的情况。
• 缩进和续行对齐应与 Xcode 的 Control-I（重新缩进）输出一致，并使用项目的缩进设置。将此规则应用于调用、声明、条件、链式调用和闭包；换行位置遵循下方示例。
• 仅当仓库已使用下方所示的分隔符风格时，才为较大的类型添加分节。与相邻文件保持完全一致：有些文件只使用 // MARK: 行，其他文件则会在其后添加框线注释。扩展类型时，保留现有分节名称和顺序。

// MARK: View Lifecycle
// ====================================
// View Lifecycle
// ====================================

• 对于扩展文件，如果符合相邻文件的风格，则在文件作用域使用相同的分隔符，并使用与上下文相符的分节名称。
• 对于新的顶层文件，优先只包含一个主要类型。不要仅为遵循风格而拆分现有文件；支持类型、扩展和协议的分组方式应遵循附近代码的惯例。
• 如果附近代码采用按不同协议职责拆分扩展或文件的方式，则优先采用这种方式。
• 创建新文件时，将职责明确的扩展文件命名为 Type+Purpose.swift。如果周边模块已有按主题分组相关扩展的惯例，则遵循该惯例。
• 按照本地顺序放置初始化方法、生命周期方法、操作方法／委托方法和私有便捷方法。简单的存储属性应放在这些分节之前。
• 遵循所在文件的 self. 使用惯例。在视图控制器代码中，如果文件始终显式使用 self.，则应保持一致；不要全局添加或移除 self.。
• 如果 SwiftLint 配置定义了 always_on_same_line 或 always_on_line_above，则遵循这些规则。否则，将 @available、@Test、@ViewBuilder 和 @Model 放在其声明的上一行。属性包装器属性应与其声明放在同一行；声明超过配置的长度限制时，遵循本地换行方式。
• 遵循本地换行方式和配置的行长度限制；不要重新排版无关代码。换行方式不明确时，阅读 references/line-wrapping.md 中的示例。遵循仓库的复杂度限制，仅在确实存在局部例外时使用作用范围最小的 swiftlint:disable。

命名、访问权限和文档

• 使用清晰、地道的 Swift 命名，并采用与周边目标一致的显式访问级别。除非接口要求更宽的访问范围，否则将实现细节设为 private。
• 对不需要子类化的引用类型，如果符合类型的用途，优先使用 final。
• 当调用方需要观察但不需要修改时，使用 private(set)。
• 为公共／共享 API 编写英文文档注释，并为设计意图或不明显的平台限制编写注释。不要添加仅仅重复代码、标注时间或提及 LLM／流程的注释。
• 保留有用的注释、MARK 和分节分隔符。仅当注释不再准确时才更新。

Swift 和 Apple API

• 优先使用标准 Swift 语言特性和部署目标已支持的平台框架。避免为常规工作引入第三方依赖。
• 对必须满足的提前退出条件使用 guard，并及时返回。明确处理预期的失败情况。
• 保持闭包和异步工作易于阅读；当存储的回调或生命周期可能导致控制器被不必要地保留时，弱引用捕获 self。
• 在共享代码中谨慎使用 #if os(...) 或 #if targetEnvironment(...)，并在可行时保持共享接口一致。
• 遵循本地的可用性检查风格。除非有明确要求，否则不要更改部署兼容性。

测试

• 遵循现有测试文件的框架和结构。对于 XCTest 目标中的新测试，除非该目标正在积极迁移，否则使用 XCTest。其他情况下，优先使用 Swift Testing——import Testing、@Test、#expect 和 #require。
• 让测试聚焦于特定行为，以行为命名，并使用仓库现有的测试夹具和辅助工具。若不改变现有 XCTest 测试的行为，就予以保留；不要仅为风格而迁移。

最终检查

提交 Swift 代码前，重新阅读已更改的上下文，并确认保留了分隔符、本地顺序、导入项、可见性、平台边界以及相关的 SwiftLint 限制。进行实际更改时，若已配置仓库的定向 lint 命令，请运行该命令，并执行最相关的构建或测试验证。