Fundamentals
The following items are called out as points to remember in this excellent book by Krzysztof Cwalina and Brad Abrams.
| Do | Design frameworks that are both powerful and easy to use. |
| Do | Explicitly design for a broad range of developers with different programming styles, requirements, skill levels, and using different programming languages. |
| Do | Understand the broad range of developers using multi language frameworks. |
| Do | Make sure that the API design specification is the central part of the design of any feature that includes a publicly accessible API. |
| Do | Define top usage scenarios for each major feature area. |
| Do | Ensure that the scenarios correspond to an appropriate abstraction level. |
| Do | Design APIs by first writing code samples for the main scenarios and then defining the object model to support the code samples. |
| Do | Write main scenario code samples in at least two different language families (i.e. VB.Net and C++) |
| Do Not | Rely solely on standard design methodologies when designing the public APIs layer of a framework. |
| Do | Organize usability studies to test APIs in main scenarios. |
| Do | Ensure that each main feature area namespace contains only types that are used in the most common scenarios. |
| Do | Provide simple overloads of constructors and methods. |
| Do Not | Have members intended for advanced scenarios on types intended for mainline scenarios. |
| Do Not | Require users to explicitly instantiate more than one type in the most basic scenarios. |
| Do Not | Require that users perform any extensive initialization before they can start programming basic scenarios. |
| Do | Provide good defaults for all properties and parameters (using convenience overloads) if possible. |
| Do | Communicate incorrect usage of APIs using exceptions. |
| Do | Ensure the APIs are intuitive and can be successfully used in basic scenarios without referring to the reference documentation. |
| Do | Provide great documentation with all APIs. |
| Do | Make the discussion about identifier naming choices a significant part of specification reviews. |
| Do Not | Be afraid to use verbose identifier names. |
| Do | Involve user education experts early in the design process. |
| Consider | Reserving the best type names for the most commonly used types. |
| Do | Use exception messages to communicate framework usage mistakes to the developer. |
| Do | Provide strongly typed APIs if at all possible. |
| Do | Ensure consistency with the .Net Framework and other frameworks your customers are likely to use. |
| Avoid | Many abstractions in mainline scenario APIs. |
| Consider | A layered framework with high-level APIs optimized for productivity and 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 (i.e., they contain many types). |
| Do | Ensure that layers of a single feature area are well integrated. |