API设计指南(译)

API的设计在软件系统中的重要性不言而喻，在swift.org上看到一篇“API Design Guidelines”，虽然是就Swift而言，但对于其它语言也有不少可以借鉴的地方，在这里粗略翻译一二，作交流用途，比较随性，有些删改，如果需要看原文，请移步 https://swift.org/documentation/api-design-guidelines/  。

---

API设计指南

基本原则

• 清晰，是第一要务。API方法和属性一处声明，到处调用，我们需要设计的使用起来简单明了。当我们评估一个设计的时候，单看其声明是基本不够的，通常需要置于具体使用场景，确保在使用时清晰明了。
• 清晰远比简明重要。虽然代码可以写的紧凑，但是用最少的字符写最少的代码绝非我们的目标，如果说Swift代码简练，那也是强类型系统的一个副产品，可以减少样板代码。
• 每个声明都进行文档注释。写文档可以加强对设计的深刻认知，不要拖延。如果发现自己不能简单地描述API的功能的话（bad smell），很可能存在设计问题。

(Swift代码注释建议，略去)

命名

用起来更加清晰

• 包括所有必须的词语，以免混淆。
• 忽略不必要的词语。命名中的每一个词语对使用者都有显著意义。
• 对于变量名、参数名、以及参考类型名，应根据其角色命名，而不是其约束。
• 对于弱类型参数信息进行补充，让参数角色更加清晰（比如参数名增加一个名词描述角色）。

力争使用流畅

• 方法名或者函数名尽可能使用符合英语语法的形式。
• 工厂方法名称以“make”开始。
• 初始化方法和工厂方法调用时形成的短语应该不包含第一个参数。
• 根据方法或者函数的连带结果进行命名。
  • 如果没有连带结果，应该是一个名词命名。
  • 如果有连带结果，应该是一个动词命名。
  • 可变和非可变方法成对命名时应该有一致的格式。
• 对于不可变的布尔类型的方法或者属性，应该是断言的形式，比如 x.isEmpty 。
• 描述事物的协议应该以名词进行命名。
• 描述能力的协议应该以 able, ible, 或者ing作为后缀。
• 其它的类型、变量、属性、以及常量的名词应以名词命名。

用好术语

• 避免使用晦涩难懂的术语，尽可能使用通俗易懂的方法来描述。
• 合理使用术语，术语应该用在恰当的地方。
• 不要使用缩略语。

惯例

通用惯例

• 复杂度不是O(1)的计算所得属性应该注释说明其复杂度。
• 优先使用方法和属性，尽量减少使用函数。
• 遵循大小写惯例，类型和协议的命名应该是首字母大写驼峰命名，其它的应该是首字母消息驼峰命名。
• 方法名称可以共用一个基本名，如果这些方法有共同的基本含义。

参数

• 利于文档注释，利于阅读。
• 当隐含通常用法的时候，可以使用默认参数值。
• 含默认参数值的参数应该置于参数列表的后面。

参数标签（Swift，略去）

特别说明

• 闭环参数和元组成员应该设置标签（Swift）。
• 谨慎使用无限制多态，以免重载的时候发生混淆。谨慎使用Any, All开头的名称。