《.NET设计规范》——学习笔记（2.3）自说明对象原则

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

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

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

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