oh-my-docs

Summary for developers

Project maintained by italkso Hosted on GitHub Pages — Theme by mattgraham

1.API 简介

与因特网相连的端系统提供了一个应用程序接口（Application Programming Interface，API）是软件系统不同组成部分衔接的约定。

API 是电脑操作系统OS 或程序库提供给 APP 调用使用的代码，经常是软件开发工具包（SDK）的一部分。其主要目的是让应用程序开发人员得以调用一组例程功能，而无须考虑其底层的源代码为何、或理解其内部工作机制的细节。API本身是抽象的，它仅定义了一个接口，而不涉及应用程序在实际实现过程中的具体操作。

下面的这个比喻很形象：

API规定了运行在一个端系统上的软件请求因特网基础设施向运行在另一个端系统上的特定目的地软件交付数据的方式。比方说：Alice使用邮政服务向Bob发一封信，邮政服务要求Alice将信放进信封中；在信封的中央写上Bob的全名、地址和邮政编码；封上信封；在信封的右上角贴上邮票；最后将信封丢进邮箱里；邮政服务有自己的“邮政服务API”或一套规则，Alice必须这么遵循，邮政服务才能把信寄给Bob；同理，因特网也有一个发送数据的程序必须遵循的API，使因特网向接收数据的程序交付数据。—《计算机网络-自顶向下学习法》

由于近年来软件的规模日益庞大，常常需要把复杂的系统划分成小的组成部分，编程接口的设计十分重要。实际开发中，编程接口的设计首先要保证软件系统功能划分合理。良好的接口设计可以降低系统各部分的相互依赖，提高组成单元的内聚性，降低组成单元间耦合度，从而提高系统的可维护性和可扩展性。

2. API设计准则

2.1 基础（清晰、简洁、文档注释）

清晰：使用时的清晰度是最重要的目标。诸如方法、属性之类的实体仅声明一次，但可以重复使用。设计API以使这些用法清晰明了。在评估设计时，不仅仅只是阅读声明，你应该始终检查用例，确保其在上下文中清晰可见。

简洁：清晰比简洁更重要。你可以使你的Swift代码更紧凑，代码可以短，但要兼顾可读性。

文档注释：为每个声明写一个文档注释。

2.2 命名

清晰

包含所有必要的单词以避免歧义
省略不必要的词（名称中的每个单词都应在使用的地方传达重要信息）
根据变量、参数和关联类型的作用而不是其类型约束来命名它们
补偿弱类型信息以阐明参数的作用

流利

优选符合英语短语语法的方法和函数名
factory 方法以make开头
根据所起作用命名方法和函数（名词形式、动词形式）
当布尔值方法和属性的使用是非突变的时，应将其用作接收方的断言
描述某些事物的协议应使用名词
描述能力的协议应使用后缀able，ible或ing来命名（如Equatable，ProgressReporting）
其他类型，属性，变量和常量的名称应读作名词

善用术语

避免晦涩难懂的术语和缩写（尤其是非标准缩写）
使用术语时遵循既定含义
参照先例

2.3 约定

一般约定

记录任何非O（1）的计算属性的复杂度：人们通常认为属性访问不涉及大量计算，因为他们已将属性存储为mental model。当可能违反该假设时，一定要提醒他们。
首选方法和属性而不是自由函数（ free functions）：自由函数仅在特殊情况下使用。
遵循大小写约定：类型和协议的名称是UpperCamelCase，其他一切都是lowerCamelCase。
当方法具有相同的基本含义或在不同的域中操作时，它们可以共享基本名称。

形参

选择恰当的形参名称提供解释信息：即使在使用函数或方法时，形参名称不会出现，它们也具有重要的解释作用。
简化默认用法时，请使用默认参数：具有单个常用值的任何参数都是备选的默认值。
最好将具有默认值的参数放在在参数列表的末尾：没有默认值的参数通常对于方法的语义更重要，并且在调用方法时提供稳定的初始使用模式。

实参标签

当无法有效区分实参时，请忽略所有标签。
在执行保留值的类型转换的构造器中，省略第一个参数标签。
当第一个实参形成介词短语的一部分时，给它一个实参标签。
否则，如果第一个实参构成语法短语的一部分，请省略其标签，并在基本名称后附加任何前面的单词。
标记所有其他实参。

3. 特殊说明

在元组成员和闭包参数出现在 API 的位置标签化元组成员和命名闭包参数。
要特别注意不受约束的多态性（例如，Any，AnyObject和不受约束的泛型参数），以避免重载集合中的歧义。

参考资料：