Swift 文档编写：如何编写自我解释的代码

面向初学者的在线Python训练器

轻松学习Python，无需理论负担。在浏览器中直接解决带自动检查的实践任务，无需安装任何东西。

开始课程

为什么文档是开发者的超能力

想象一下：半年后您打开一个用 Swift 编写的他人项目。代码能运行，但无法理解作者为什么要这样做，而不是那样做。没有注释，变量名是 a1、temp2 这样的风格。熟悉吗？

好的文档不仅仅是对未来自己的礼貌。它是一种工具，能节省数小时的调试时间，加速新开发者的入职流程，并将混乱变为有序的系统。在本文中，我们将探讨 Swift 代码文档编写的最佳实践，从基础注释到高级 DocC。

基础：从简单注释到有意义的描述

//、/// 和 /* */ —— 何时使用

Swift 中有三种注释类型，各有其用途：

单行注释 // —— 用于快速笔记、TODO 或临时禁用代码。不要滥用：如果注释解释的是显而易见的内容，那就是多余的。
多行注释 /* */ —— 用于解释代码块或在调试时禁用整段代码。
文档注释 /// —— 这是您的主要工具。Xcode 会自动识别它们并在 Quick Help 中显示。

/// 根据半径计算圆的面积。/// - Parameter radius: 圆的半径，单位为米。/// - Returns: 面积，单位为平方米。/// - Throws: 如果 radius < 0，则抛出 `InvalidInputError.negativeRadius`。func areaOfCircle(radius: Double) throws -> Double {    guard radius >= 0 else {        throw InvalidInputError.negativeRadius    }    return Double.pi * radius * radius}

糟糕的注释 vs 好的注释

比较两种方法：

// 糟糕：显而易见的注释// 将计数器增加 1counter += 1

// 好：解释“为什么”// 使用递增操作，因为这是性能关键区域，// 而 Swift 中的 ++ 操作已废弃counter += 1

黄金法则：注释应该回答“为什么”的问题，而不是代码“做什么”。代码本身应该可读，以便“做什么”无需文字就能理解。

DocC —— 新一代文档工具

什么是 DocC，为什么它是必备工具

随着 Xcode 13 的发布，Apple 推出了 DocC（文档编译器）—— 一种将您的 /// 注释转换为精美、交互式文档的工具，可直接在 Xcode 和网页中使用。不再需要 PDF 文件和一周内就会过时的维基页面。

如何在项目中使用 DocC

设置： 在 Xcode 中选择 Product → Build Documentation。DocC 会自动收集所有已文档化的符号。
文档内部链接： 使用 `` 链接到其他类型：

/// 使用 ``NetworkManager`` 发送请求。/// 更多详情请参阅文章 <doc:NetworkGuide>。

Markdown 功能： DocC 支持标题、列表、表格、图片，甚至 Mermaid 图表：

/// # 算法流程/// 1. 检查缓存/// 2. 如果没有，则向服务器发送请求/// 3. 保存结果

为整个模块创建文档

在项目根目录添加 Documentation.docc 文件。内部使用 Markdown 结构：

// MyFramework.docc/MyFramework.md# ``MyFramework``

用于网络操作的异步库。

## Topics

### 核心组件- ``NetworkManager``- ``RequestBuilder``

### 扩展- <doc:CustomizingRequests>