在简单的使用场景中,一定要让框架无需文档就能使用。

  • 要确保API是直观的,无需查阅参考文档就能用于基本场景
    你总不希望写个“Hello World”都去查阅API文档吧。
  • 要为所有的API提供优秀的文档。
    一方面,并非所有的API都能自说明。不同的人会认为不同的API是自说明的;
    另一方面,有些人想在开始使用API之前完全理解它们。

设计自说明API时最重要的一些考虑因素:

  1. 命名
    要在规范检查中重视标识符名称的选择;
    不要担心标识符的名字太冗长;
           一眼就能看出相应的方法是做什么的,类型和参数是表示什么意思。
           而且类型的名字如果足够好,那么用到这些类型的代码会更易于立即和维护。
    要在设计过程的初期就让用户教育专家参与;
    考虑把最好的名字留给最常用的类型。
  2. 异常
    要通过异常消息来清楚地告诉开发人员对框架的误用。
  3. 强类型
    很明显,调用Customer.Name要比调用Customer.Properties["Name"]容易。
    要尽可能提供强类型API。
           如果必须使用属性包,那么应该为包中最常用的属性提供相应的强类型属性。
  4. 一致性
    要确保与.NET框架以及客户可能会使用的其他框架保持一致。
  5. 限制抽象的数量
    标准面向对象设计方法会产生大量抽象。其目的是使代码易于维护。然而如果框架中存在太多的抽象,则会要求用户对框架的架构有深入的了解,不易于用户使用。
    避免在主要场景的API中使用太多的抽象。