Framework Design Guidelines: Powerful and Easy

Continuing in the series of sharing information from the Framework Design Guidelines


Expert from 2.2 Fundamental Principles of Framework Design


Providing a development platform that is both powerful and easy to use is

one of the main goals of the .NET Framework, and should be one of your

goals if you are extending it. The first version of the Framework indeed

gave developers a powerful set of APIs, but some of them found parts of

the Framework too difficult to use.


RICO MARIANI The flip side of this is that it must not only be easy to

use the API, but it must be easy to use the API in the best possible way.

Think carefully about what patterns you offer and be sure that the most natural

way to use your system gives results that are correct, is secure against

attacks, and has great performance. Make it hard to do things the wrong


A few years ago I wrote this:

The Pit of Success: In stark contrast to a summit, a peak, or a journey

across a desert to find victory through many trials and surprises, we want

our customers to simply fall into winning practices by using our platform

and frameworks. To the extent that we make it easy to get into trouble we


True productivity comes from being able to easily create great products—

not from being able to easily create junk. Build a pit of success.



Rico really ups the ante here… as he makes very clear it is not sufficient that the API be easy to use, it must be easy to use in the right way… What APIs have you seen that are easy to use in the wrong way?

Comments (9)

  1. Sean Chase says:

    throw new System.Exception("yuck");

  2. Matthew W. Jackson says:

    I’ll second the Exception one. If you had it to do again, I’d say make System.Exception abstract, make all the exceptions that shouldn’t be caught (such as ThreadAbortException or StackOverflowException) inherit from a single base (like AsyncException), and everything else could be a SystemException. Also, the ArgumentExceptions would be more consistant and useful.

    Anyway, the big easy-to-misuse API I stumbled upon yesterday was Type.InvokeMember when late-binding COM objects. Specifically I’m talking about the "ParameterModifier[] modifiers" argument for marking arguments as by-reference. The usage of this is simply esoteric.

    Then again, a lot of things in Reflection are this way.

  3. Jonathan Allen says:

    I for one have completely given-up on reflection. I need to use late binding because some COM classes are so poorly written that none of their interfaces appear to list all the methods I know exist.

    Even though out company is mostly C#, we decided to write all the interop code in VB instead of dealing with the reflection directly.

    For example, Rational’s ClearQuest API. None of the interfaces listed in the object browser for the Entity object expose the EditEntity method. But yet VB somehow figures out how to call it anyways.

    Can tell me how VB does that?


  4. Abubakar says:

    well I wrote a code using anonymous methods, and it was the only time I didnt like my code.

  5. Geert Baeyaert says:

    I think WeakReference.IsAlive is an example of a mountain of success.

    Consider the following example:

    foreach (WeakReference wr in wrs)


    if (wr.IsAlive)


    // GC happens here




    Bam, NullReferenceException, hard to reproduce, hard to find.

    Actually, I can’t think of one example where WeakReference.IsAlive is usefull. You always have to check that the target is not null, as in the following example:

    foreach (WeakReference wr in wrs)


    Foo foo = (Foo)wr.Target;

    if (foo != null)





    Therefore, I think WeakReference.IsAlive should be made obsolete.

    (I have already submitted this on the Feedback center, vote for it if you agree with me)

  6. The problem

    Back when ASP.NET was first introduced, I had pretty high hopes that the new controls would…

  7. The problem Back when ASP.NET was first introduced, I had pretty high hopes that the new controls would