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开头的名称。

API设计指南(译)的更多相关文章

  1. 组件接口(API)设计指南-文件夹

    组件接口(API)设计指南-文件夹 组件接口(API)设计指南[1]-要考虑的问题 组件接口(API)设计指南[2]-类接口(class interface) 组件接口(API)设计指南[3]-托付( ...

  2. REST API设计指导——译自Microsoft REST API Guidelines(四)

    前言 前面我们说了,如果API的设计更规范更合理,在很大程度上能够提高联调的效率,降低沟通成本.那么什么是好的API设计?这里我们不得不提到REST API. 关于REST API的书籍很多,但是完整 ...

  3. REST API设计指导——译自Microsoft REST API Guidelines(二)

    由于文章内容较长,只能拆开发布.翻译的不对之处,请多多指教. 另外:最近团队在做一些技术何架构的研究,视频教程只能争取周末多录制一点,同时预计在下周我们会展开一次直播活动,内容围绕容器技术这块. 所有 ...

  4. RESTful API 设计指南 (转)

    RESTful API 设计指南 2016-02-23 ImportNew (点击上方公号,可快速关注) 作者:阮一峰 链接:http://www.ruanyifeng.com/blog/2014/0 ...

  5. 来自HeroKu的HTTP API 设计指南(中文版)

    原文转自:http://get.jobdeer.com/343.get 来自HeroKu的HTTP API 设计指南(中文版) 翻译 by @Easy 简介 本指南中文翻译者为 @Easy ,他是国内 ...

  6. RESTFul API设计指南及使用说明

    RESTFul API设计指南及使用说明 一. 协议 API与用户的通信协议,使用HTTP协议. 二. 域名 应尽量将API部署在专用域名之下(http://api.example.com) 也可以将 ...

  7. RESTful API 设计指南,RESTful API 设计最佳实践

    RESTful API 设计指南,RESTful API 设计最佳实践 网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机.平板.桌面电脑.其他专用设备......). ...

  8. Rest Framework简介 和 RESTful API 设计指南

    使用Django Rest Framework之前我们要先知道,它是什么,能干什么用? Django Rest Framework 是一个强大且灵活的工具包,用以构建Web API 为什么要使用Res ...

  9. [置顶] 来自 HeroKu 的 HTTP API 设计指南(中文版)

    转载:http://get.jobdeer.com/343.get 来自 HeroKu 的 HTTP API 设计指南(中文版) 翻译 by @Easy 简介 本指南中文翻译者为 @Easy ,他是国 ...

随机推荐

  1. JDBC各种数据库连接URL关键代码

    通过JDBC连接数据库时,各个数据库有着不同的URL格式,为了方便大家使用,我在以下提供了常见的7种数据库连接示例代码,请根据实际需要进行相应的更改. 1.Oracle数据库 Class.forNam ...

  2. YTU 2945: 编程:五元向量的运算

    2945: 编程:五元向量的运算 时间限制: 1 Sec  内存限制: 128 MB 提交: 151  解决: 85 题目描述 用习惯了的运算符操作新定义的类对象,这是OO方法给我们带来的便利.下面要 ...

  3. jquery 中cache为true与false 的区别

    $.ajax({type: "get",cache: false,url: url,success: function (msg) { }}); cache为true与false ...

  4. Avoiding memory leaks

    Android applications are, at least on the T-Mobile G1, limited to 16 MB of heap. It's both a lot of ...

  5. JAVA web简单的登录界面jsp实现

    此次试验所用到的软件是myeclipse10,tomcat7,Dreamweaver,sqlserver2008数据库.可以实现用户使用用户名和密码登录.如果登录成功,页面会显示登录成功,如果密码错误 ...

  6. C++ 多线程与并发

    1. 非原子操作 这些非原子操作在被编译为汇编代码后不止一条指令. 自加.自减少: new 关键字: 申请内存: 调用构造函数: pInst = new T; // 对于这样一个赋值语句,更是包含了如 ...

  7. 【转】axios全攻略

    随着 vuejs 作者尤雨溪发布消息,不再继续维护vue-resource,并推荐大家使用 axios 开始,axios 被越来越多的人所了解.本来想在网上找找详细攻略,突然发现,axios 的官方文 ...

  8. 使用Python操作Redis应用场景

    1. 安装pyredis 首先安装pip   1 2 3 4 5 6 7 8 <SHELL># apt-get install python-pip ...... <SHELL> ...

  9. Educational Codeforces Round 23 A-F 补题

    A Treasure Hunt 注意负数和0的特殊处理.. 水题.. 然而又被Hack了 吗的智障 #include<bits/stdc++.h> using namespace std; ...

  10. hdu5410(完全背包变形)

    这是道完全背包,关键点在于如何处理每种物品,第一次放时,价值为A+B,以后放时,价值为A. 所以有三种决策,对于第i种物品,要么不放,要么是作为第一个放,要么是第二个以后放. 作为第一个放时,需要用到 ...