Friday, March 27, 2009

Framework Design Guidelines: the System.* namespace

by BradA via Brad Abrams on 3/27/2009 5:03:00 AM

Today we have a guest post from Kit George who is the keeper of much of our internal Framework Design Guidelines.  This is the stuff that Krys and I based a the book on.  I asked Kit to post this internal information so you can get a feeling for what our guidelines are and why…. and so you can call us on it if we mess it up ;-)

As always, feedback and comments are welcome!

It is clear that there’s a bit of confusion over the namespace guidelines. Here is our attempt at make this clear.  We know this will remain a contentious issue, but the goal of these guidelines is to clarify:

• The .NET platform is not limited to any one single redistributable.
• Types in the System.* namespace define the .NET platform. We of course carry existing types with us that go against this rule, but moving forward, we will adopt this approach
• Something within Microsoft.* is produced by Microsoft but is not part of the .NET platform
• APIs that are not necessarily going to be shipped are differentiable from APIs that are intended to be shipped

The .NET platform (which includes Silverlight, the full .NET Framework, the .NET Compact Framework, etc) continues to be that set of managed functionality, produced by Microsoft, that is for general application use. This doesn’t mean APIs that are guaranteed to be useful to every application (we can’t guarantee that), but APIs which can be used by many different application purposes and styles. These APIs may be shipped in different ways. There are other interesting questions that aren’t addressed by namespaces.

How does a user determine if an API is in Silverlight, but not in the .NET Framework 3.5? How does a user determine if an API is officially supported? How does a user determine if an API is usable on a device? These issues will be resolved using other mechanisms, not namespaces.

The following guidance comes out of this position and is used internally to help us follow the position.

Microsoft will use System.* for namespaces that are planned to be exposed publically and are considered part of the .NET platform.

Types that are part of the platform have expectations around quality, compatibility, consistency of design, and general usability. Types that are suitable for the platform portray the following characteristics:

• We expect the API to be used by a wide variety of applications

              Examples: string, central collections (List<T>, etc.), Linq, data

• The API may be specific to a high level, but part of a general purpose application model (Label, TextBox, etc.)

               Examples: Web, Windows.Forms, WPF

• The API is formed of common abstractions and primitives that allow higher-level components to communicate

              Examples: System.IO, System.Globalization

• The API has had considerable design invested and is well-factored, reviewed, and consistent with the system. Depending on the ship vehicle, the size and deployment impact will have been considered
  
• The API is finished and therefore, doesn’t require significant changes once publically available

Microsoft will use use Microsoft.* for namespaces that are planned to be shipped by the team and are considered application or non-platform components.

This applies to APIs/namespaces that are:

• Part of an application. Applications are by definition, not useful to a variety of other scenarios/applications.

              Example: Visual Studio, Office, SharePoint

• Non-Core. Non-Core can be interpreted as ‘not for general Application use’. If you can’t see the API being used in most scenarios, or many application styles, it’s likely non-core. This includes APIs that serve a subset platform (for example, a common platform layer inside Office), APIs that are for a constrained task (such as MSBuild), or for a particular application type. This is NOT to say these cannot be moved/generalized in future versions if appropriate

Example: MSBuild, Office Infrastructure APIs

Microsoft will use Microsoft.Experimental.* for namespaces that are seeking consumer input, but have no committed ship plan

At Microsoft, In order to ship a CTP of a feature, a team and divisional commitment to officially productize the API is in place. Nothing is final, but the conviction and intent is there. Prior to this stage, there is literally no commitment or plans to ship the API. Use Microsoft.Experimental.* to communicate to customers that the feature in question is long-lead and may not see the light of day. Once the team is committed to shipping the API and is working on a schedule, feel free to use the most appropriate namespace based on the purpose of the productized type.

Avoid changing the namespace of a type once you’ve decided to ship the type publically (once you’ve reached the Beta stage).

Changing the namespace from a Beta onwards is costly to consumers. This issue is absolutely secondary to getting the namespace right, but consider the impact when making such decisions.