Swift 中 // 与 /// 的区别
在 Swift 编程中，注释是代码可读性和可维护性的关键部分。
虽然 // 和 /// 都用于添加注释，但它们的目的和功能却截然不同。
简单来说：
// 是普通单行注释，用于向阅读代码的开发者解释实现细节。
/// 是文档注释 (Documentation Comment)，用于生成 API 文档和在 Xcode 中提供“快速帮助”。
// (普通单行注释)
这是一种最常见的注释形式，会被编译器完全忽略。它的主要作用是为代码的读者（包括未来的你）提供上下文。
核心用途：
解释一段复杂算法的实现思路。
留下待办事项，例如 // TODO: Refactor this logic。
临时禁用某行或某几行代码进行调试。
解释某个“魔法数字”或硬编码值的含义。
示例
swift
Show full code block
// 计算用户的最终得分
func calculateFinalScore(baseScore: Int) -> Int {
let bonus = 10 // 为所有用户提供固定奖励分数
// TODO: 未来需要根据用户等级应用不同的奖励系数
let finalScore = baseScore + bonus
// print("Debug: Final score is \(finalScore)") // 临时禁用的调试代码
return finalScore
}
这些注释仅存在于源代码中，不会被 Xcode 用于任何外部功能。
/// (文档注释)
这是一种功能强大的特殊注释。当你将它放在一个声明（如函数、类、结构体、协议、枚举或属性）的正上方时，Swift 编译器和 Xcode 会解析它，并将其转化为可交互的文档。
核心用途：
快速帮助 (Quick Help)：在 Xcode 中，按住 Option 键并单击代码中的符号（函数名、类名等），会弹出一个包含这些注释内容的帮助窗口。
代码自动补全：在你输入代码时，Xcode 的自动补全列表会显示这些注释作为提示。
文档生成：可以使用 Jazzy 等工具，从这些注释中自动生成专业、美观的网页版 API 文档。
文档注释使用一种特殊的 Markdown 语法来标记不同的部分，例如参数、返回值和警告。
示例
swift
Show full code block
/// 计算两个整数相加的和。
///
/// 通过这个函数可以快速获得两个整数的和。函数内部会处理加法操作。
///
/// - Note: 这个函数非常基础，适用于大多数加法场景。
/// - Warning: 当结果超出 `Int` 类型的最大值时，会发生整数溢出，函数不会抛出错误。
///
/// - Parameter value1: 第一个加数。
/// - Parameter value2: 第二个加数。
/// - Returns: 两个参数相加后的整数结果。
func sum(of value1: Int, and value2: Int) -> Int {
return value1 + value2
}
/// 代表一个用户的基本信息。
struct User {
/// 用户的唯一ID，不可更改。
let id: UUID
/// 用户的显示名称。
var displayName: String
}
当你在 Xcode 中按住 Option 并点击 sum 函数时，你将看到一个格式化好的弹窗，清晰地展示了函数的摘要、参数和返回值信息。
多行注释变体
Swift 也为这两种注释提供了多行（块）版本。
/* ... */ (普通多行注释) 等同于在多行上使用 //。
swift
/*
这是一个普通的多行注释块。
非常适合用来详细解释一段复杂的业务逻辑，
或者临时注释掉一大段代码。
*/
/** ... */ (多行文档注释) 等同于在多行上使用 ///。
swift
/**
计算两个整数相加的和。
通过这个函数可以快速获得两个整数的和。函数内部会处理加法操作。
- Parameter value1: 第一个加数。
- Parameter value2: 第二个加数。
- Returns: 两个参数相加后的整数结果。
*/
func anotherSum(of value1: Int, and value2: Int) -> Int {
return value1 + value2
}
最佳实践
为所有 public 和 internal 的 API 编写 /// 文档注释。
这是一种专业习惯，极大地提升了代码库的可维护性和团队协作效率。
使用 // 来解释复杂的内部实现。
当一段代码的逻辑不那么直观时，用它来留下线索，帮助他人（和未来的自己）快速理解。
遵循这个简单的规则，你的 Swift 代码将会变得更加清晰、专业和易于使用。
