Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries

Appendix C. Sample API Specification

MANY OF THE GUIDELINES described in this book are best considered up front during the initial design. This appendix contains an example of an API specification^[1] that should be written early in the process of designing a framework feature. Although such an API specification does not describe full details of the feature, it does highlight the most important elements of the design to nail down up front. This example is heavily based on an actual specification we wrote for a feature of the .NET Framework. Its content is as simple as we could find, but it’s a good illustration of the parts, flow, and priorities of a specification intended to describe framework APIs that adhere to the guidelines described in this ...