0Pricing
Swift Academy · 课时

样式指南与 API 设计指南

使用清晰的 名称 、经过斟酌的 参数标签 、合理的 默认值 和简洁的 文档注释 ，设计易用的 Swift API。

样式指南与 API 设计指南 是 CoddyKit 上的免费 Swift Academy 课时。 这是第 2 节课，共 3 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Swift Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Swift Academy 课程共包含 3 节课。

原则

优秀的 API 应当易读、可预测且简洁。

  • 能够描述意图的名称
  • 实用的参数标签
  • 为常见情况提供默认值
  • 简洁的文档和示例

命名基础

操作 => 动词，数据 => 名词。避免使用会隐藏含义的缩写。

// Prefer clear, simple names.
// BAD:
func doCalc(_ a: Int, _ b: Int) -> Int { a + b }

// GOOD:
func sum(_ a: Int, _ b: Int) -> Int { a + b }

// BAD (ambiguous):
struct Cfg { let v: Int }
// GOOD (nouns for data types):
struct Configuration { let retries: Int }

print(sum(2, 3))  // 5

参数标签

标签可以帮助调用位置自然地读起来：remove(at:)、insert(_:at:)。

// Choose labels that explain a parameter's role.
// BAD:
func remove(_ index: Int) { print("remove", index) }

// BETTER:
func remove(at index: Int) { print("remove at", index) }

// Mixed labels:
func insert(_ item: String, at index: Int) {
    print("insert", item, "at", index)
}

remove(at: 2)
insert("a", at: 1)

良好的默认值

使用默认参数，让常见调用保持简短，同时仍然提供灵活性。

// Provide defaults to cover the 80% case.
func greet(_ name: String, times: Int = 1, shout: Bool = false) {
    let msg = shout ? "HELLO, \\(name)!" : "Hello, \\(name)!"
    for _ in 0..<times { print(msg) }
}

greet("Ana")                 // default: once, not shouting
greet("Ben", times: 2)
greet("Cara", shout: true)

效果与可变性

让效果清晰可见：对状态变更使用可变方法，并在适当时使用 private(set) 暴露只读视图。

// Prefer pure functions when possible; name mutating effects explicitly.
struct Counter {
    private(set) var value = 0
    mutating func increment(by amount: Int = 1) { value += amount }
}

var c = Counter()
c.increment()
c.increment(by: 3)
print("value =", c.value) // 4

记录 API 文档

文档注释提示：

  • 以一句话摘要开头。
  • 说明它做什么，而不是如何做。
  • 展示一个简短的调用示例。
  • 仅在重要时注明前置条件或性能陷阱。

标签使用理由

快速检查：什么时候应该添加外部标签？

回顾

回顾：优先使用清晰的名称，添加读起来流畅的标签，为常见调用提供默认值，明确表达效果，并用一个示例让文档保持简短。

常见问题解答

「样式指南与 API 设计指南」课时是免费的吗？

是的 — 「样式指南与 API 设计指南」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Swift Academy 课程的其余内容，请升级到 CoddyKit PRO。 Swift Academy 课程共包含 3 节课。

「样式指南与 API 设计指南」这节课中我会学到什么？

使用清晰的 名称 、经过斟酌的 参数标签 、合理的 默认值 和简洁的 文档注释 ，设计易用的 Swift API。 你通过在浏览器中直接运行的动手代码来练习 Swift Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Swift Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Swift Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 2 节课，共 3 节。

「样式指南与 API 设计指南」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Swift Academy 课中编写并运行代码吗？

能。每节 Swift Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. SwiftFormat / SwiftLint 基础
  2. 样式指南与 API 设计指南
  3. 记录代码（DocC 入门）
← 返回 Swift Academy