The Little Manual of API Design

https://people.mpi-inf.mpg.de/~jblanche/api-design.pdf

• Characteristics of Good APIs 好的API特点
  • Easy to learn and memorize 容易学习和记忆
  • Leads to readable code 产生可读代码
  • Hard to misuse 很难误用
  • Easy to extend 容易扩展
  • Complete 完备性
• The Design Process API设计过程
  • Know the requirements 了解需求
  • Write use cases before you write any other code 在编写代码前编写用例
  • Look for similar APis in the same library 参考相似的API，了解背景，取精华其糟粕
  • Define the API before you implement it 在实现前先定义
  • Have you peers review your API 同事评议你的API设计
  • Write several examples against the API 用自己设计的API编写几个例子看看
  • Prepare for extensions 为扩展做准备
  • Don't publish internal APIs without review 在评议之前先不要发布内部API
  • When in doubt, leave it out. 如果有什么不确定的话，先不要设设计出来
    • Functionality, classes, methods, parameters, etc.
    • You can always add, but you can never remove
• Design Guidelines API设计准则
  • Choose self-explanatory names and signatures 自解释的名字
  • Choose unambiguous names for related things 给相关事物取名一定要消除歧义
  • Beware of false consistency. 虚假一致性
    • 两个API从语义上相似，但是如果底层代价或者是调用方式存在很大差异的话，
    • 需要在API设计上将这些反应出来，让使用者意识到这种差异
  • Avoid abbreviations 避免过度缩写
  • Prefer specific names to general names. 使用更加准确的命名
  • Don't be a slave of an underlying API's naming practices. 不要被底层API的命名规则限制和约束
  • Choose good defaults 选择好的默认值
  • Aoivd making your APIs overly clever 不要让API过度智能（产生难以解释的副作用）
  • Pay attentions to edge cases 验证极端测试用例
  • Be careful when defining virtual APIs 是否有必要设计成为虚函数
  • Strive for property-based APIs 尽量设计成基于属性的API
  • The best API is no API 少做决定，少写API