Framework Design Guidelines: Supporting Experimentation

Continuing in our weekly blog post series that highlights a few of the new image[5]_thumb[2]_thumb[2]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.

Comments (4)

  1. Shail says:

    Hello Brad,

    I have finished chapter 3 of the book just now about naming guidelines . There is guideline which says that name of the types should not match with name of types in .Net framework. And if that is the case this means that its a "Sloppy" design ( As per krzysztof Cwalina’s annotation )

    But consider this case ( Its a real world case for my current project )

    In my Business domain I have "Services" and "Providers". These terms are used in the domain for last 20 years. Its a common term used by customer and now also by developers. So I need to name my classes as "Service" and "Provider".

    But this is somewhere clashing with the .Net framework types.

    I can find alternate name for my classes. But what should be your solution to this, assuming that you are in my place ????


  2. BradA says:

    Shail – Thanks for your comments..  My first thought is if you can be slightly more specific in your naming… Perhaps you want HealthCareSerivces or EmployeeServices, etc..    Or, perhaps you could ask what part of the  .NET Framework uses the “Services” name and if that is likelycommon to be used with your component or not.  If it is not then maybe you don’t have as much of an issue.

  3. Shail says:

    Yes, Brad you are right, I think I can use the word "Service", I have just added a note in my technical document not to get confused with a web service or any other type from .Net Framework. I will make sure all will read note at first. Also it will stay in my Business Namepspace say XYZ, so even there will be a new type in .Net named "Service". There will be less hassels. In case of service I can not be specific as a service is a service, its differentiated by its type and there can be 100 types

    For provider class, I have named it as "ServiceProvider"

    That is more close to business term and more specific. After all there was one very good annotation from krzysztof Cwalina

    "There is no perfect Framework" 🙂

    I should leave something for my next assignment. Annotations in the book are really helpful and add more value and are kind of POC to the context.


Skip to main content