Code Analysis Team Blog : Framework Design Guidelines

David Kean's new blog

David M. Kean — Tue, 10 Jun 2008 17:00:00 GMT

For those that are interested, I've just started a new personal blog, Dave's Box, where I will be talking about FxCop, Framework Design Guidelines, and the recently announced Managed Extensibility Framework.

I've just posted a couple of posts detailing changes we made to FxCop 1.36:

FxCop now ships with the spell checker libraries
Reference resolution changes in Code Analysis and FxCop

You can subscribe via the one of the two following links:

Subscribe via reader
Subscribe via email

What do you want to see in the second edition of Framework Design Guidelines?

David M. Kean — Tue, 15 Jan 2008 18:00:00 GMT

Krzysztof and Brad have announced they are working on the second edition of the awesome Framework Design Guidelines and are looking for feedback on what they should put in it.

For those that don't know, a lot of our Code Analysis rules are based on the writings in this great book, so expect to see additional rules in the future based on the new guidelines in the second edition.

To provide feedback, head over to Krzysztof's blog and post a comment.

Krzysztof Cwalina on Framework Design Guidelines and API Design

David M. Kean — Thu, 10 May 2007 18:00:00 GMT

A lecture on API design by Krzysztof Cwalina (the brains behind the Framewok Design Guidelines) has been posted on the Research Channel.

This class presents best practices for designing frameworks that are reusable object-oriented libraries. The guidelines are applicable to frameworks ranging in size and in their scale of reuse from large system frameworks to small components shared among several applications. They started as a small set of naming and design conventions, but have been enhanced, scrutinized, and refined to a point where they are generally considered the canonical way to design frameworks at Microsoft. They carry the experience and cumulative wisdom of thousands of developer hours, over three versions of the .NET Framework.

I've seen Krzysztof (and Brad) present this personally and it is definitely worth seeing. Set some time aside this weekend to watch this and enjoy.

How to Design Exception Hierarchies

David M. Kean — Thu, 01 Feb 2007 19:00:00 GMT

Krzysztof Cwalina, owner of the Framework Design Guidelines, has written a great post on designing exception hierarchies. He gives a great overview on the different categories of exceptions, which are placed under two main buckets he calls usage and system, and the right situations to throw them.

This post also goes hand-in-hand with some of the previous posts on this blog:

FAQ: What exception should I throw instead of the reserved exceptions that DoNotRaiseReservedExceptionTypes warns against?
FAQ: Why does FxCop warn against catch(Exception)? (Part 1, Part 2 and Part 3)

FAQ: Why does DoNotExposeGenericLists recommend that I expose Collection instead of List? [David Kean]

David M. Kean — Fri, 28 Apr 2006 00:20:00 GMT

DoNotExposeGenericLists fires when I publicly expose List<T> via a field, method, property, or parameter. Why?

Although Krzysztof briefly touched on this last year, we wanted to expand on this a little through the use of examples.

The first reason is that List<T> is designed for speed and for use as an internal implementation detail, whereas Collection<T> is designed for extensibility.

Collection<T> provides 4 overridable methods; ClearItems, InsertItem, RemoveItem and SetItem, which allow a derived class to be notified when a collection has been modified. In contrast, List<T> provides none.

As an example, let’s say in V1.0 of your framework, you have a Person class that exposes a collection of addresses. You could choose to expose this via a property that returns either a List<Address> or Collection<Address> :

List<Address>:

public class Person
{
    private List<Address> _Addresses = new List<Address>();

    [...]

    public List<Address> Addresses
    {
        get { return _Addresses; }
    }
} 

Collection<Address>:

public class Person
{
    private Collection<Address> _Addresses = new Collection<Address>();

    [...]

    public Collection<Address> Addresses
    {
        get { return _Addresses; }
    }
} 

Along comes V2.0 of your framework, and your users have asked you to expose an event that gets raised every time an address is added or removed from the collection. Had you originally headed down the List<T> route, you’ve now painted yourself in a corner. There is no way to be notified (without breaking existing clients) of when an external object modifies the collection. However, had you chose to expose Collection<T>, you can now do something like the following:

public class Person
{
    private AddressCollection _Addresses = new AddressCollection(this);

    [...]

    public event EventHandler AddressChanged;

    public Collection<Address> Addresses
    {
        get { return _Addresses; }
    }

    protected virtual void OnAddressChanged(EventArgs e)
    {
        if (AddressChanged != null)
        {
            AddressChanged(this, e);
        }
    }

    private void RaiseAddressChanged()
    {
        OnAddressChanged(EventArgs.Empty);
    }

    private class AddressCollection : Collection<Address>
    {
        private Person _Owner;

        public AddressCollection(Person owner)
        {
            _Owner = owner;
        }

        protected override void InsertItem(int index, Address item)
        {
            base.InsertItem(index, item);

            _Owner.RaiseAddressChanged();
        }

        protected override void RemoveItem(int index)
        {
            base.RemoveItem(index);

            _Owner.RaiseAddressChanged();
        }

        protected override void ClearItems()
        {
            base.ClearItems();

            _Owner.RaiseAddressChanged();
        }
    }
}

From the above code you can see that you are still exposing the same Collection<Address> property, so no breaking change was made, however, your users can now be notified when someone changes the collection.

The second reason why you shouldn’t expose List<T>, is because it exposes too many members, many of which are not relevant in most situations. In contrast, Collection<T> exposes only a small number. For those that are relevant, it is easy to encapsulate List<T> and expose those that you want to make use of via a class that derives from Collection<T>. For example, continuing on from above:

public class AddressCollection : Collection<Address>
{
    public AddressCollection() : base(new List<Address>())
    {
    }

    public Address Find(Predicate<Address> match)
    {
        // We know Items is actually a List<Address> as we passed it to the constructor
        List<Address> items = (List<Address>)Items;

        return items.Find(match);
    }
}

As you can see, the AddressCollection simply calls the underlying List<T>'s Find implementation, saving you from having to implement your own.

If you have any questions or issues with Managed Code Analysis or FxCop (including DoNotExposeGenericLists), don’t hesitate to head over to the FxCop Forum.

Seen any Microsoft produced code that doesn't pass Code Analysis/FxCop? [David Kean]

David M. Kean — Wed, 12 Apr 2006 07:51:00 GMT

As some of you may already know, the majority of the Developer Division is currently planning features to be included in the next version of Visual Studio (Orcas). As part of this planning phase, the Managed Code Analysis (FxCop) team is beginning to work with other teams around Microsoft to ensure that any customer facing code released in Orcas is Code Analysis clean.

We’re also asking for your help. If you’ve ever come across code that hasn’t passed Code Analysis whether that be generated by custom tools, compilers, MSDN Library examples, sample applications, templates, designers, articles or any other Microsoft produced code, we want to hear about it.

Blog about it, tell your colleagues, managers, friends, spouses (if they write code), mailing lists, forums and any other medium that you can think of that if they have ever come across code that made them say ‘Damn Microsoft, I wish they would follow their own guidelines’ - then the Code Analysis team wants to hear from them.

As an example of what kind of issues we are looking for, see the following Product Feedback Center bugs:

Prevent generated DSL code from producing FxCop warnings
Windows Service template Dispose method does not pass FxCop analysis
AssemblyInfo to be FxCop compliant by default
"exception" expansion code sniplet has incorrect "public" visibility for serialisation contructor. FxCop rule violation

You can either post your feedback via a comment below or by using this blog's contact form.

FAQ: Why do some sources recommend extending ApplicationException while FxCop does not? [Michael Fanning, David Kean]

David M. Kean — Thu, 06 Apr 2006 06:21:00 GMT

TypesShouldNotExtendCertainBaseTypes fires on types that derive from ApplicationException and DoNotRaiseReservedExceptionTypes on members that throw ApplicationException. Why?

There are several outdated documents floating around on the web (some orginally published by Microsoft) recommending that application developers extend ApplicationException. However, this guidance was revised several years ago for a couple of reasons:

It deepens the class hierarchy and presents additional complications for consumers writing exception handlers without providing additional value.
It prevents the reuse of existing exception classes defined in the Base Class Library (BCL).

The official Microsoft Design Guidelines, particularly the Catching and Throwing Standard Exception Types section, have only recently been revamped to include this new information. Both Krzysztof Cwalina and Brad Abrams, who own the Framework Design Guidelines at Microsoft, have both blogged on this issue (ApplicationException considered useless and Introducing the .NET Framework Standard Library Annotated Reference).

If you see any MSDN samples or articles that use ApplicationException (or violate any FxCop rule, for that matter), please file a bug on the Microsoft Connect.