[Framework Design Guideline]

[Framework Design Guideline]基础知识

最近在读<Framework design guideline>, 感觉其中Framework的许多设计经验同样适用于业务类库的设计，甚至对于服务的设计也同样适用。

日常的设计和编码中，书中提到的许多原则也有所领悟，但一直无法系统的组织起来。

所以此文把这些指导经验都整理起来，一作为备忘，二也是为这些平常只能靠感觉的东西建立成文的指导。本文只整理了一些对于业务应用类库开发更有用的原则。

一、什么是好的设计

• Well-Designed Frameworks are simple.
• Well-Designed Frameworks are expensive to design.
• Well-Designed Frameworks are full of trade-offs.
• Well-Designed Frameworks borrow from the past.
• Well-Designed Frameworks are designed to evolve.
• Well-Designed Frameworks are integrated.
• Well-Designed Frameworks are consistent.

二、如何做出好的设计

Design frameworks that are both powerful and easy to use.

好的类库/框架应该既能满足复杂的业务场景又易于使用。也就是简单的事情简单做，复杂的事情可以做。

The Principle of scenario-driven design.

Make sure that the API design specification is the central part of the design of any feature that includes a publicly accessible API.

Define top usage scenarios for each major feature area.

Ensure that the scenarios correspond to an appropriate abstraction.

Design APIs by first writing code samples for the main scenarios and then defining the object model to supprot the code samples.

Don’t rely solely on standard design methodologies when designing the public API layer of a framework.

在设计一个公共类库的时候，不要单独依赖某一种设计方法，包括一些经典的面向对象的设计方法。因为这些方法可能更多的针对可维护性，而不是framework的可用性。

最好使用场景驱动、原型、可用性研究等方法，再配合迭代。

Organize usability studies to test APIs in main scenarios.

应该在开发早期就对主要业务场景进行可用性研究，因为可用性的问题可能导致底层设计的改变。

The Principle of Low Barrier to Entry

Ensure that each main feature area namespace contains only types that are used in the most common scenarios.

Types used in advanced scenarios should be place in subnamespaces.

Provide simple overloads of constructors and methods. A simple overload has a very small number of parameters, and all parameters are primitives.

Don’t require users to explicitly instantiate more than one type in the most basic scenarios. 
Don’t require that users perform any extensive initialization before they can start programming basic scenarios.

Provide good defaults for all properties and parameters.

Communicate incorrect usage of APIs using exceptions.

异常应该能够清楚表达什么导致了这个异常，并描述如果处理。

The Principle of Self-Documenting Object Models

Ensure that APIs are intuitive and can be successfully used in basic scenarios without referring to the reference documentation.

Provide great documentation with all APIs.

Make the discussion about identifier naming choices a significant part of specification reviews.

Don’t be afraid to use verbose identifier names.

Consider reserving the best type names for the most commonly used types.

Use exception messages to communicate framework usage mistakes to the developer.

Provide strongly typed APIs if at all possible.

Avoid many abstractions in mainline scenario APIs.

The Principle of Layered Architecture

Using a layered framework with high-level APIs optimized for productivity, and using low-level APIs optimized for power and expressiveness.

Avoid mixing low-level and high-level APIs in a single namespace if the low-level APIs are very complex.