.Net Framework Design Guidelines

The following items are called out as points to remember in this excellent book by Krzysztof Cwalina and Brad Abrams.


DoDesign frameworks that are both powerful and easy to use.
DoExplicitly design for a broad range of developers with different programming styles, requirements, skill levels, and using different programming languages.
DoUnderstand the broad range of developers using multi language frameworks.
DoMake sure that the API design specification is the central part of the design of any feature that includes a publicly accessible API.
DoDefine top usage scenarios for each major feature area.
DoEnsure that the scenarios correspond to an appropriate abstraction level.
DoDesign APIs by first writing code samples for the main scenarios and then defining the object model to support the code samples.
DoWrite main scenario code samples in at least two different language families (i.e. VB.Net and C++)
Do NotRely solely on standard design methodologies when designing the public APIs layer of a framework.
DoOrganize usability studies to test APIs in main scenarios.
DoEnsure that each main feature area namespace contains only types that are used in the most common scenarios.
DoProvide simple overloads of constructors and methods.
Do NotHave members intended for advanced scenarios on types intended for mainline scenarios.
Do NotRequire users to explicitly instantiate more than one type in the most basic scenarios.
Do NotRequire that users perform any extensive initialization before they can start programming basic scenarios.
DoProvide good defaults for all properties and parameters (using convenience overloads) if possible.
DoCommunicate incorrect usage of APIs using exceptions.
DoEnsure the APIs are intuitive and can be successfully used in basic scenarios without referring to the reference documentation.
DoProvide great documentation with all APIs.
DoMake the discussion about identifier naming choices a significant part of specification reviews.
Do NotBe afraid to use verbose identifier names.
DoInvolve user education experts early in the design process.
ConsiderReserving the best type names for the most commonly used types.
DoUse exception messages to communicate framework usage mistakes to the developer.
DoProvide strongly typed APIs if at all possible.
DoEnsure consistency with the .Net Framework and other frameworks your customers are likely to use.
AvoidMany abstractions in mainline scenario APIs.
ConsiderA layered framework with high-level APIs optimized for productivity and low-level APIs optimized for power and expressiveness
AvoidMixing low-level and high-level APIs in a single namespace if the low-level APIs are very complex (i.e., they contain many types).
DoEnsure that layers of a single feature area are well integrated.