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

lihuu — Sun, 30 Nov 2025 17:55:22 +0800

本指南适用于 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 支持）	类型/方法/属性文档	✔ 是
`/** ... */`	多行文档注释	长段落说明	✔ 是

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