Continuing in our weekly blog post series that highlights a few of the new additions to the Framework Design Guidelines 2nd edition.. This content is found in the Framework Design Principles section of Chapter 2: Framework Design Fundamentals. I love the history and real world color Chris brings to this guideline with his annotation.
Some APIs lend themselves to experimentation and some do not. To be easy to experiment with, an API must do the following:
Allow easy identification of the right set of types and members for common programming tasks. A namespace intended to hold common scenario APIs that contains 500 types, out of which only a handful are actually important in common scenarios, is not easy to experiment with. The same applies to mainline scenario types with many members that are intended only for very advanced scenarios.
In the early days of Windows Presentation Foundation (WPF) project we ran into this exact issue. We had a common base type named Visual from which almost all of our elements derived. The problem was that it introduced members that directly conflicted with the object model of the more derived elements, specifically around children. Visual had a single hierarchy of child visuals for rendering, but our elements wanted to introduce domain-specific children (like a TabControl only accepting TabPages). Our solution was to create a VisualOperations class that had static members that worked on a Visual instead of complicating the object model of every element.