Xcode 注释标签（Annotation Tags）与最佳实践指南

本指南适用于 Swift / SwiftUI / macOS/iOS 应用开发，帮助你在工程中正确、优雅、专业地使用 Xcode 支持的注释标签，提高代码可读性、可维护性和团队协作效率。

1. Xcode 支持的注解标签一览表

以下标签是 Xcode 原生支持 的，它们在导航栏、Issue Navigator 中具有特殊行为。

注解标签	Xcode 行为	用途	官方支持
`// MARK:`	在导航栏创建分组 Section	组织代码结构	✔ 是
`// MARK: -`	分组 + 分隔线	更强的视觉分割	✔ 是
`// TODO:`	出现在 Issue Navigator → Todos	待办事项	✔ 是
`// FIXME:`	出现在 Issue Navigator → Todos	待修复的问题	✔ 是
`// WARNING:`	构建时出现黄色警告 ⚠️	强调重要问题	✔ 是
`// ERROR:`	构建时报红色错误 ❌	阻止构建（调试用）	✔ 是
`// NOTE:`	普通注释，无特殊行为	补充说明	✔ 是
`///`	文档注释（Quick Help 支持）	类型/方法/属性文档	✔ 是
`/** ... */`	多行文档注释	长段落说明	✔ 是

2. 注解标签详解

2.1 `// MARK:` —— 代码分区（最常用）

用于将大型 Swift 文件分块，让导航结构更清晰。

示例：

        
// MARK: - Public API
// MARK: - Private Helpers
// MARK: - UI
// MARK: - Life Cycle

作用：

在 Xcode 导航栏显示为“章节”
可折叠/展开
组织代码结构

2.2 `// TODO:` —— 未来要做的事

出现在 Issue Navigator → Todos 中。

        
// TODO: Add network volume support

2.3 `// FIXME:` —— 当前已知问题

用于标记 bug 或需要修正的代码。

        
// FIXME: Sorting breaks cursor position; needs stable ID mapping.

也会显示在 Issue Navigator。

2.4 `// WARNING:` —— 重要的警告

编译时会出现 ⚠️。

// WARNING: This method blocks the main thread.

2.5 `// ERROR:` —— 强制构建失败（调试阶段偶尔用）

// ERROR: Remove before shipping final build

很少使用，但在防止某些危险代码进入发布版时有用。

2.6 `// NOTE:` —— 普通提示性注释

无特殊行为。

// NOTE: Scroll offset is preserved only when switching between panes.

2.7 文档注释 `///` —— Swift 官方推荐

用于类、属性、函数的文档，可在 Quick Help 中显示。

支持 Markdown：

        
/// Reloads files for the current path.
/// - Important: Must be called on the main actor.
/// - Returns: Loaded file list.
func reload() async -> [FileItem]

2.8 多行文档注释 `/** ... */`

适合长段落说明或复杂逻辑。

        
/**
 Scans a directory recursively.

 - Warning: Does not detect symlink cycles.
 - Parameters:
   - path: Directory to scan.
 */

3. 注释最佳实践（Swift 官方风格 + 工程实际经验）

3.1 注释“为什么（why）”，不注释“做了什么（what）”

❌ 这样写没意义：

        
// Move cursor down
cursorIndex += 1

代码已经看得懂。

✅ 正确注释是解释“为什么这样做”：

        
// Clamp cursor to avoid going out of bounds after reloads
cursorIndex += 1

3.2 用 `// MARK:` 清晰分区大型文件

推荐用法：

        
        
        
    
// MARK: - State
// MARK: - Derived State
// MARK: - Public API
// MARK: - Actions
// MARK: - Private Helpers
// MARK: - Async Operations
// MARK: - Subviews (SwiftUI)

SwiftUI View 文件推荐：

        
// MARK: - Body
// MARK: - Subviews
// MARK: - Actions
// MARK: - Gestures

3.3 所有对外公开的 API 都写 `///` 文档注释

这会在 IDE 中显示，非常有用：

        
/// Move cursor by the specified delta.
/// - Parameter delta: Positive for down, negative for up.
func moveCursor(by delta: Int)

3.4 复杂逻辑写多行注释解释背景

        
/*
 Handling sandbox-restricted directories.
 Accessing some system paths (e.g. /usr, /private) may fail with
 NSCocoaErrorDomain Code=257. Show locked-folder UI in this case.
*/

3.5 用 TODO / FIXME 管理技术债与未来功能

        
// TODO: Add preview panel
// FIXME: Cursor breaks after file deletion

3.6 不要给显而易见的代码写注释

例如：

        
// Return true
return true

完全多余。

4. 示例：PaneState.swift 的最佳实践注释模板

        
        
        
    
// MARK: - Cursor State

/// The ID of the file the cursor is pointing at.
/// - Note: This is the single source of truth.
///         `cursorIndex` is always derived from this value.
@Published var cursorFileId: String

/// Derived cursor index based on `cursorFileId`.
/// - Returns: 0 if the target file no longer exists.
var cursorIndex: Int {
    activeTab.files.firstIndex { $0.id == cursorFileId } ?? 0
}


// MARK: - Actions

/// Move cursor up or down within valid bounds.
/// - Parameter delta: Positive to move down, negative to move up.
func moveCursor(by delta: Int)


/// Reload directory contents.
/// - Throws: If directory access is denied (sandbox / no full disk access).
@MainActor
func reload() async throws


// MARK: - Private Helpers

/// Clamps an index within the valid range of files.
private func clamp(_ i: Int) -> Int {
    max(0, min(i, activeTab.files.count - 1))
}

5. SwiftUI View 文件最佳实践模板

        
// MARK: - Body

var body: some View {
    content
}

// MARK: - Subviews

private var content: some View { ... }

private var fileList: some View { ... }

// MARK: - Actions

private func handleFileClick(_ file: FileItem) { ... }
private func handleKeyEvent(_ key: Key) { ... }

6. 最终总结

所有 // MARK:, // TODO:, // FIXME:, // WARNING: 都是 Xcode 官方支持的注解。
文档注释 /// 是 Swift 标准，推荐用于所有公共 API。

Swift 注释最佳实践总结：

注释“原因”，不要注释“行为”
用 MARK 清晰组织文件
用 /// 文档注释给 API 写说明
用 TODO / FIXME 管理未来工作
多行注释用于解释复杂逻辑
不对显而易见的代码加注释

Xcode 注释标签（Annotation Tags）与最佳实践指南

1. Xcode 支持的注解标签一览表

2. 注解标签详解

2.1 // MARK: —— 代码分区（最常用）

2.2 // TODO: —— 未来要做的事

2.3 // FIXME: —— 当前已知问题

2.4 // WARNING: —— 重要的警告

2.5 // ERROR: —— 强制构建失败（调试阶段偶尔用）

2.6 // NOTE: —— 普通提示性注释

2.7 文档注释 /// —— Swift 官方推荐

2.8 多行文档注释 /** ... */