Api 设计规范 (转载)

09 252016

1. 拼写要准确

接口函数一旦发布就不能改了,要保持兼容性,拼写错误也不能改了,所以要仔细检查拼写,否则会被同行嘲笑很多年。
著名悲剧:unix 的 creat

2. 不仅是英文单词不要拼错,时态也不要错。
比如:
返回bool的判断函数,单数要用 is 复数要用are,这样你的命名就和文档中的描述保持了一致性。
表示状态的变量或者函数要注意时态,比如 onXxxxChanged 表示xxx已经变化了,isConnecting表示正在连接。
正确的时态可以给使用者传递更丰富的信息。

3. 函数最好是动宾结构
动宾结构就是  doSomething,这样的函数命名含义明确
比如: openFile, allocBuffer, setName
如果这个函数的动词宾语就是这个对象本身,那么可以省略掉宾语

4. 属性命名最好是定语+名词
比如 fileName, maxSize, textColor

5. 不要用生僻单词,这不是秀英语的地方,也不要用汉语拼音
比如:rendezvous,估计大多数人要去查词典才知道什么意思,这个词源自法语,是约会的意思。
Symbian OS里有个用它命名的函数,开发Symbian的是英国人,也许人家觉得很平常吧,反正我是查了词典才知道的。

6. 不要自己发明缩写
除非是约定俗成已经被广泛使用的缩写,否则老老实实用完整拼写。
坏例子:  count->cnt, manager->mngr password->pw button->btn
现代的IDE都有很好的自动完成功能,名字长一点没关系的,可读性更重要。

7. 保持方法的对称性,有些方法一旦出现就应该是成对的,
比如 有open就要有close,有alloc就要有free,有add就要有remove,这些单词基本是固定搭配的,使用者就很容易理解。
如果 open对应clear就有点让人困惑了。

8. 站在使用者的角度去思考,API设计也要讲究用户体验。
好的API设计应该是符合直觉,能望文生义的,让使用者能用尽量简洁的代码完成调用。


作者:姚冬
链接:http://www.zhihu.com/question/31363461/answer/51984535
来源:知乎
著作权归作者所有,转载请联系作者获得授权。

版权信息

原文作者: 石头记

原文链接: http://1m85.com/40.html

版权所有: 本文为博主原创文章,转载请标明出处。