Design Guidelines Book (The Principle of Scenario-Driven Design)

The Design Guidelines have been published on MSDN and as a part of the CLI ECMA specification (Partition V, Annex D). This was long time ago and we have been receiving lots of requests for an update and also for something that can be read offline. So, here you go — Brad and I have…


Design Guidelines Update: Dispose Pattern

Joe, just posted an update to the Design Guidelines describing issues relared to IDisposable, Finalization, and resource management.

Design Guidelines Update: Exception Throwing

Exception Throwing Exception throwing guidelines described in this section require a good definition of the meaning of execution failure. Execution failure occurs whenever a member cannot do what it was designed to do (what the member name implies). For example, if OpenFile method cannot return an opened file handle to the caller, it would be…


Rationale for Generic Type Parameter Naming Guidelines

The recent type parameter naming guidelines update resulted in a very lively discussion. I thought I would provide some rational for the recent changes. But first, I would like to first thank all of you who got involved in the debate. We have had debates like that for ages about many issues related to our products,…


Design Guidelines Update: Names of Generic Type Parameters

After receiving lots of feedback from internal and external community (see here for example), we decided to modify the generic type parameter naming guidelines. The previous guidelines allowed only single letter type parameter names. The new guidelines allow and even encourage descriptive names.   Here are the new guidelines. Names of Generic Type Parameters Do…


Design Guidelines Update: Factories vs. Constructors

Joe has recently spent some time beefing up the Factory vs. Constructor guidelines. This subject has been the center of lots of intenral debates. Finally, we agreed on the fllowing: Factories The most common and consistent way to create an instance of a type is via its constructor. However, sometimes a preferable alternative is to use…


Design Guidelines Digest

Lots of people have asked me to create a short version of the Design Guidelines. Here it is. You can also email me directly at if you would like to get an MS Word copy of the digest, hich has a bit better formatting. [UPDATE: I recently updated this document and placed it online….


Design Guidelines Update: Evolving Managed APIs

Kit George (member of the BCL team) blogged an update that we just did to our Design Guidelines. The new guidelines talk issues related to evolving managed APIs. See  

Design Guidelines Update: Optional Features Pattern

This is a relatively major update to the Design Guidelines. It describes and formalizes a very common .NET Framework Pattern/Idiom for exposing optional functionality/service of an API (for example canceling a stream operation, as not all streams support cancellation). Optional Features In designing your class library, you may find cases where some implementations of your…


Design Guidelines Update: Enum Design

This is a recent update to the Design Guidelines. One of the most interesting additions is the section about adding values to enums (at the end of the section). This was one of the guidelines were getting an agreement across the whole company was quite challenging. Kit (frequent poster to the BCL Team Blog) spent…