[转]Joshua Bloch关于API设计的Keynote

Joshua Bloch关于API设计的Keynote

API设计的过程

Gather Requirements–with a Healthy Degree of Skepticism：以use cases的形式。
Start with Short Spec–1 Page is Ideal：让越多的人参与越好，随着信心的增加不断扩充。
Write to Your API Early and Often：在实现API之前，在描述之前，扩充之后继续编写
Writing to SPI is Even More Important：在发布之前先写至少3个插件
Maintain Realistic Expectations：多数API设计都限制过多，有犯错误的心理准备
通用原则

API Should Do One Thing and Do it Well：功能应该容易说明
API Should Be As Small As Possible But No Smaller：有疑问的时候就忽略，追求power-to-weight比
Implementation Should Not Impact API：不要让实现细节泄漏到API中
Minimize Accessibility of Everything：最大化信息隐藏
Names Matter–API is a Little Language：名字应该是顾名思义的；一致的；代码应该像散文
Documentation Matters
Document Religiously：仔细的说明状态空间
Consider Performance Consequences of API Design Decisions：坏的决策影响性能；不要wrap API来获取性能
Effects of API Design Decisions on Performance are Real and Permanent
API Must Coexist Peacefully with Platform
类设计

Minimize Mutability：如果只能是mutable的，保证小的状态空间
Subclass Only Where It Makes Sense：不能为了容易实现，就让一个Public类继承另外一个Public类。
Design and Document for Inheritance or Else Prohibit it：继承违背了封装
方法设计

Don’t Make the Client Do Anything the Module Could Do
Don’t Violate the Principle of Least Astonishment
Fail Fast–Report Errors as Soon as Possible After They Occur：编译时刻最好；运行时刻，第一次坏方法调用的时候
Provide Programmatic Access to All Data Available in String Form：否则，客户端代码必须解析字符串
Overload With Care：避免模糊的overloadings；如果必须提供，保证相同的参数有相同的行为
Use Appropriate Parameter and Return Types：Favor interface types over classes for input；Use most specific possible input parameter type；Don’t use string if a better type exists；Don’t use floating point for monetary values；Use double (64 bits) rather than float (32 bits)
Use Consistent Parameter Ordering Across Methods
Avoid Long Parameter Lists：3个或更少最好
Avoid Return Values that Demand Exceptional Processing
异常设计

Throw Exceptions to Indicate Exceptional Conditions：不要迫使客户端代码使用异常来控制流程；不要悄无声息的失败
Favor Unchecked Exceptions
Include Failure-Capture Information in Exceptions