How to Design a Good API and Why it Matters

http://wenku.baidu.com/link?url=DNX_g0Q2q3oWM5PaAZUjUVQU09CigFjf9Qr87d1ZY2RhoEwNoUbzQ0OOYfgvlUFGBq_H0VRHBWcbW7ikzsPSTWwfZolFKXBMeIngv3Rv_Sq



Characteristics of a Good API
• Easy to learn
• Easy to use, even without documentation
• Hard to misuse
• Easy to read and maintain code that uses it
• Sufficiently powerful to satisfy requirements
• Easy to extend
• Appropriate to audience


API Should Do One Thing and Do it Well

Functionality should be easy to explain
_ If it's hard to name, that's generally a bad sign
_ Good names drive development
_ Be amenable to splitting and merging modules


API Should Be As Small As Possible But No Smaller

API should satisfy its requirements
• When in doubt leave it out
_ Functionality, classes, methods, parameters, etc.
_ You can always add, but you can never remove
• Conceptual weight more important than bulk
• Look for a good power-to-weight ratio


Implementation Should Not Impact API

Implementation details
_ Confuse users
_ Inhibit freedom to change implementation
• Be aware of what is an implementation detail
_ Do not overspecify the behavior of methods
_ For example: do not specify hash functions
_ All tuning parameters are suspect
• Don't let implementation details “leak” into API
_ On-disk and on-the-wire formats, exceptions


Minimize Accessibility of Everything

Make classes and members as private as possible
• Public classes should have no public fields
(with the exception of constants)
• This maximizes information hiding
• Allows modules to be used, understood, built,
tested, and debugged independently


Names Matter–API is a Little Language

Names Should Be Largely Self-Explanatory
_ Avoid cryptic abbreviations
• Be consistent–same word means same thing
_ Throughout API, (Across APIs on the platform)
• Be regular–strive for symmetry
• Code should read like prose




  • 0
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值