Brad Abrams : New Guideline

Framework Design Guidelines: LINQ

BradA — Thu, 13 Mar 2008 17:53:14 GMT

Wow, it feels like old times... I am happy that we are posting a new proposal for additions to the framework design guidelines. Mitch has worked hard on these, and we have reviewed them internally and now it is time for your comments. Please do chime in!

LINQ Framework Design Guidelines

Thanks!

Design Guideline Update: handling nulls in public APIs

BradA — Thu, 16 Dec 2004 18:27:00 GMT

We had a recent thread internally that resulted in me updating the guidelines below… Please let me know if you have any questions or comments.

Do provide overloads for methods with optional arguments. If a method takes some arguments that are not required provide overloads of the method without the optional arguments. See section X.Y on method overloading. That is if you have this method here geometry is optional, provide an overload without it as well.
public void DrawGeometry(Brush brush, Pen pen, Geometry geometry);
public void DrawGeometry(Brush brush, Pen pen);

Do allow null to be passed for optional arguments. If a method takes optional arguments that are reference types, allow null to be passed to indicate the default value should be used. This avoids the problem of having to check for null before calling an API as shown below:
if (brush == null) DrawGeometry(pen, geometry);
else DrawGeometry(pen, geometry, brush);

Annotation (Adam Smith): It sure seems that we're providing a less startling API if we define reasonable, expected behavior when "null" is passed for a param. If that's really impossible, sure, throw an exception, but to throw when there's a consistent, non-crashing thing we could have done seems unhelpful.

Design Guideline update: put cleanup code in finally blocks

BradA — Fri, 03 Dec 2004 22:35:00 GMT

Another new guideline.. this one sparked a lot of discussion during our internal review, lets see if I cleaned it up well enough or not ;-)

Do put cleanup code in finally blocks.
Even code that immediately follows a catch() can be interrupted by an asynchronous exceptions (an exception caused by another thread, such as ThreadAbortException. Once the try block is entered, your cleanup code will be guaranteed to run if you put it in a finally block. Notice that the CLR uses a two pass exception model which means that exception filters[1] all the way up the call stack are executed after the catch block but before the finally block.

Incorrect: Cleanup() will not be executed in the face of an asynchronous exception

try

{

//...

}

catch //catching *ALL* exceptions and

// swallowing them

{

//...

}

//Execute clean up in the exceptional and

//non-exceptional case

Cleanup();

Correct: Cleanup() will be executed even in the face of an asynchronous exception*

try

{

//...

}

catch // catching *ALL* exceptions and

// swallowing them

{

//...

}

finally

{

//Execute clean up in the exceptional and

// non-exceptional case

Cleanup();

}

Notice that in this example we catch all exceptions. That is rarely the correct coding practice. It is used here to better illustrate the point of the guideline. Please see section X.y on exception handling.

Many methods perform some form of cleanup. All methods that perform cleanup should do so in a finally block. Here is an example:

public void UpdateSet(){
   Set mySet = new Set();
   try{

      foreach (string s in GetValues() ) {
          mySet.Add(s);
      }      ...
   }finally{
      Set.Close();
   }
}

[1] Exception filters are not supported by C#, but supported by VB, IL, etc

* There are some async exceptions such as StackOverflow and Rude Aborts that can cause even code in the finally to be skipped. However these situations are relatively rare and don't change the spirit of this guideline.

New Design Guideline: Parameter validation

BradA — Thu, 02 Dec 2004 07:27:00 GMT

More guideline updates from the Security push (as Soma said earlier this year, the push is now upon us!)

Do be aware that mutable values may have changed after they were validated. If the operation is security sensitive you are encouraged to make a copy, then validate and process the argument.
The following sample code demonstrates the issue. The DeleteFiles() method does not create a copy of the filenames array before validation as such it is subject to a race condition.

/// <summary>

/// Deletes all the files passed in if they all pass validation, throws otherwise.

/// </summary>

public void DeleteFiles(string[] filenames)

{

if (!ValidateFiles(filenames)) throw new ArgumentException("Files must be local");

Thread.Sleep(1);//force a race to demonstrate the problem

foreach (string s in filenames)

{

Console.WriteLine("Thread1: Deleting file: {0}", s);

/*TODO: File.Delete(s); */

}

private bool ValidateFiles(string[] filenames)

{

foreach (string s in filenames)

{

if (s.Contains("..")/*TODO: real test */)

{

return false;

}

else

{

Console.WriteLine("Thread1: '{0}' passes validation", s);

}

} //end for

return true;

}

Notice we force the race condition with the Thread.Sleep() call, without the call the problem may still happen depending on other factors on the machine.

This is exploited by the calling code forking off a thread to change the values in the array after validation occurs.

static void Main(string[] args)

{

Program p = new Program();

string[] names = { "one.txt", "two.txt" }; //init to a set of valid values

Thread hackerThread = new Thread(delegate(object obj) //set up hacker thread

{

names[1] = @"..\..\boot.ini";

Console.WriteLine("Thread2: changing 1 to '{0}'", names[1]);

});

hackerThread.Start();

p.DeleteFiles(names); //call the API being hacked

}

The output from this code is:

Thread1: 'one.txt' passes validation

Thread1: 'two.txt' passes validation

Thread2: changing 1 to '..\..\boot.ini'

Thread1: Deleting file: one.txt

Thread1: Deleting file: ..\..\boot.ini

Notice that Thread1 validates ‘one.txt’ and ‘two.txt’, but ends up deleting ‘one.txt’ and ‘..\..\boot.ini’ because thread2 is able to change one of the values after validation happens.

The fix for this problem is relatively simple, if expensive. Simply use Array.Copy() to create a local copy of the array *before* validating and performing operations on it. Notice Array.Copy() only does a shallow copy, this works for arrays of strings as strings are immutable, but if you are dealing with an array of some mutable type (such as StringBuilder, boxed value type, etc) you’d have to do a deep copy for the array.

/// <summary>

/// Deletes all the files passed in if they pass validation, throws otherwise.

/// </summary>

public void DeleteFiles(string[] filenames)

{

string [] filenamesCopy = new string[filenames.Length];

Array.Copy(filenames, filenamesCopy,filenames.Length);

if (!ValidateFiles(filenamesCopy)) throw new ArgumentException("Files must be local");

Thread.Sleep(1);//force a race

foreach (string s in filenamesCopy)

{

Console.WriteLine("Thread1: Deleting file: {0}", s);

/*TODO: File.Delete(s); */

}

With this change, we throw an exception as expected or delete only the safe values depending on a race.

New Design Guideline: Null Paramarrays

BradA — Wed, 01 Dec 2004 06:52:00 GMT

Based on some security reviews we are doing on the system in general I added this implementation note to the Design Guidelines.

Do be aware that null could be passed in for the paramarray. You should validate that that paramarray is not null before processing (see section on parameter passing for more infomration).

static void Main(string[] args)

{

Sum(1, 2, 3, 4, 5); //result == 15

Sum(null); //throws null reference exception

}

static int Sum(params int[] values)

{

int sum = 0;

foreach (int i in values)

{

sum += i;

}

return sum;

}

New Design Guideline: Be consistent in naming parameters when overloading, overriding and implementing interfaces

BradA — Mon, 04 Oct 2004 22:24:00 GMT

We have seen this come up a more than a few times in WinFX API reviews so I thought it was worth adding a quick guideline… As always, please let me know if you have any questions or comments.

You can check out the base design guidelines and my incremental updates.

Do be consistent in naming parameters when overloading, overriding and implementing interfaces. This discipline increases the developer perception of connection and interrelation between the methods. FxCop rule request Xxx.

Implementing Interfaces:

public class IComparable

{

int CompareTo(object x, object y);

}

public class FooComparable : IComparable

{

//Correct

public int CompareTo(object x, object y)
{

}

//Incorrect

public int CompareTo(object value1, object value2)

{

}

Overriding Members:

public class Object

{

public virtual bool Equals(object obj)

{

}

public class MyClass

{

//Correct

public overide bool Equals(object obj)

{

}

//Incorrect

public overide bool Equals(object value)

{

}

Overloading:

public class String {

//Correct

public int IndexOf (string value) {}

public int IndexOf (string value, int startIndex) {}

public int IndexOf (string value, int startIndex, int endIndex) {}

//Incorrect

public int IndexOf (string value) {}

public int IndexOf (string str, int startIndex) {}

public int IndexOf (string value, int beginIndex, int endIndex) {}

}

New Design Guideline: Avoid Protected Static

BradA — Thu, 09 Sep 2004 13:49:00 GMT

Here is a minor update to the design guidelines around subclassing. It is based on this quiz I did a last week. Please let me know if you have any questions or comments.

As always, you can check out the base design guidelines and my incremental updates.

Avoid Protected Statics. Carefully consider what information you expose in and use from static protected data because parallel subclass can access it. Consider the following example. Even though Child and Malicious are parallel and unrelated, Malicious is able to access state the Child sets. The core issue here is that sensitive data should not be exposed as protected as any arbitrary subclass can use access it. FxCop rule <tbd> flags any protected static member for review of this issue.

public class Base

{

static protected String _password;

}

public class Child : Base

{

static Child()

{

_password = "Darb";

}

public class Malicious : Base

{

public static String StealPassword()

{ return _password; }

}

Notice, any subclass of Base can access _password, the Child class is not required.

Annotation (BradA): Notice that, unlike C++, the runtime does eliminate this problem for protected instance data as a subclass is only allowed to access instance data through its own type. In the example below Malicious is not allowed to access _password through an instance of Child.

public class Base

{

protected String _password;

}

public class Child : Base

{

public Child(string password)

{

_password = password;

}

public class Malicious : Base

{

public String StealPassword(Child child)

{ return child._password; }

}

New Design Guideline: Virtual Members

BradA — Fri, 13 Aug 2004 05:26:00 GMT

As you might guess from my last few posts, I have been doing some thinking about virtual members. Here are the updated guidelines. Please let me know if you have any questions or comments.

As always, you can check out the base design guidelines and my incremental updates.

Do not call virtual members from constructors. Calling virtual methods during construction will cause the most derived override to be called, even though the most derived constructor has not been fully run yet. FxCop Rule: ConstructorsShouldNotCallBaseClassVirtualMethods

Consider the example below which prints out “value != 42, what is wrong” when a new instance of Derived is created. The implementer of the derived class assumes that the value will be set to 42 before anyone can call Method1(). But that is not true because the base class’s constructor is called before the Derived class’s constructor finishes, so any calls it makes to Method1() causes the problem.

public class Base

{

public Base()

{

Method1();

}

public virtual void Method1() {

Console.WriteLine("In Base's Method1()");

}

public class Derived: Base

{

private int value;

public Derived()

{

value = 42;

}

public override void Method1()

{

if (value == 42) Console.WriteLine("value == 42, all is good");

else Console.WriteLine("value != 42, what is wrong?");

}

When a virtual method is called, the actual type that executes the method is not selected until runtime. When a constructor calls a virtual method there is a chance that the constructor for the instance that invokes the method has not executed.

Annotation : In unmanaged C++, the vtable is updated during the construction so that a call to a virtual function during construction only calls to the level of the object hierarchy that has been constructed.It’s been my experience that as many programmers are confused by the C++ behavior as the managed behavior. The fact is that most programmers don’t think about the semantics of virtual calls during construction / destruction – until they have just finished debugging a failure related to this.

Either behavior is appropriate for some programs and inappropriate for others. Both behaviors can be logically defended. For the CLR, the decision is ultimately based on our desire to support extremely fast object creation.

Annotation: Within a "program" a developer can deal with the behavior that is implemented. If there are different policies chosen in different "programs" interop becomes a serious issue. Therefore any API between separate "programs" (apps, add-ins) should not depend on behavior of virtual methods. C++ direct calls are another manifestation of this.

Do not call virtual members from destructors. Calling virtual members will result in possibly surprising behavior because the most derived implementation of the virtual method will be run.
FxCop Rule: TBD (XXX)

Consider the example below, for an instance of derived a C++ developer would expect Base::DoCleanUp() to run with the base class’s finalizer is run however because the runtime virtualizes the call to the runtime type of the instance is used and Derived::DoCleanUp() is called. Notice this issue can be worked around my making DoCleanUp() no virtual or requiring overrides to insert a call to the base classes implementation.

public class Base

{

public virtual void DoCleanUp() {

Console.WriteLine("Do Base's Cleanup");

}

~Base()

{

DoCleanUp();

}

public class Derived: Base

{

public override void DoCleanUp()

{

Console.WriteLine("Do Derived Cleanup");

}

~Derived()

{

DoCleanUp();

}

New API Design Guideline: Enums

BradA — Tue, 18 May 2004 17:32:00 GMT

There are a few topics that are likely to generate a long thread of discussion whenever they come up Exceptions, finalization, and Enums are among them Kit George spent a fair amount of time working with folks across WinFX on how to “correctly” use Enums. There is of course, more to say here, but I think this is a good first start. As always, love to have your feedback.

http://blogs.msdn.com/kcwalina/archive/2004/05/18/134208.aspx

New Design Guidelines Posted: Resources and Xml

BradA — Tue, 04 May 2004 20:35:00 GMT

If you have not been tracking Kris’s blog, you might have missed that we recently posted two new design guidelines for Framework developers. As always comments are very welcome, even encouraged.

Exposing XML Data

Resources

Please see the design guidelines and other incremental updates.

Minor update to Enum size guideline

BradA — Sat, 06 Mar 2004 00:13:00 GMT

Here is a minor clarification on the enum size guidelines. Please let me know if you have any questions or comments.

As always, you can check out the base design guidelines and my incremental updates.

Do use Int32 (the default in most programming languages) as the underlying type of an enum unless any of the following is true:

1. The enum represents flags, and you expect many flags (>32) now or in the future.

Annotation (BradA): This may not be as uncommon a concern as you might first expect. We are only in V2.0 of the .NET Framework and we are already running out of values in the CodeDom GeneratorSupport enum. In retrospect, we should have used a different mechanism for communicating support of a larger underlying type.

2. The type needs to be different than Int32 for backward compatibility.

3. You expect to it to be common to create a hundred or more instances of the enum by using the enum as a field in a frequently instantiated structure or class; storing many instances in arrays, files, etc. In such cases smaller is better. If you expect to the enum to be used mostly as a singleton for flow of control the size makes little differences.

Annotation (BradA): Note that for in memory usage you should be aware that managed objects are always DWORD aligned so you effectively need multiple enums or other small structures in an instance to pack a smaller enum with to make a difference as the total instance size is always going to be rounded up to a DWORD.

Annotation (BradA): Keep in mind it is a binary breaking change to change the size of the enum type once you have shipped, so chose wisely, with an eye on the future. Our experience is that Int32 is usually the right choice and thus we made it the default.

Design Guidelines Update: Exception Message Guidelines

BradA — Thu, 29 Jan 2004 06:27:00 GMT

It has become clear to me recently that we could be doing a better job with exception messages. I took these guidelines from a set that the UE team on the .NET Framework uses. Love to hear your comments, issues, and suggestions.

7.3.2 Exception Error Messages

Do provide rich and meaningful message text targeted at the developer when throwing an exception

Annotation (BradA): Unintelligible, incomplete error messages are the most common reason why users contact support. Error messages that precisely and lucidly describe the problem, the probable causes, and the solutions or workarounds help users understand why the error occurred, how to fix it, and how to avoid it in the future. In addition, all exception strings are localized, which makes it especially important to deliver messages that are clearly stated and complete.

Do localize exception messages

Annotation (BradA): Many developers that use the .NET Framework are non-English speaking. We localize our entire documentation set (including the huge API reference). Localizing the error message helps non-English speakers feel more comfortable on our platform.

Do use grammatically correct exception messages. Make the assumption that code may present the user with the exception message.

Each sentence in a description string of an exception should end in a period. This way code that generically displays an exception message to the user does not have to handle the case where a developer forgot the final period, which is relatively cumbersome and expensive.

Do provide useful information that helps the user diagnose the problem. For example, rather than using “Bad link,” try “Link target does not exist”

Do be precise. For example, “Missing file name extension” is better than “File not found.”

Do describe the problem. For example, “Disk full” is better than “File error.”

Do use third-person, simple present or past tense, and active voice.

Do use a neutral tone. For example, change the tone in “Bad input” to “Command is unrecognizable.” to avoid blaming the user.

Do start with search-relevant words. Use passive voice or more complex construction if necessary. For example, “Log file {0} is full.” is preferable to “{0} log file is full.”

Do use complete sentences. For example, use “Binding is too long.” rather than “Binding too long.”

Do not use exclamation points. Notice the difference between “Command is unrecognizable!!” and simply “Command is unrecognizable.”

Do not personify (imply that programs think or feel). For example, “Node parameter cannot use Windows NT protocols.” is better than “Parameter node does not speak any of our protocols.”

Do not start with an article or variable. Use searchable words at the beginning instead. For example, “Log file {0} is full.” is preferred to “{0} log file is full" or “The {0} log file is full."

Do not use quote marks for emphasis.

Do not provide security sensitive information in an exception message.

Design Guideline Update: Uri vs. string

BradA — Tue, 13 Jan 2004 00:14:00 GMT

ChrisAn blogged about this a few weeks ago and I am happy to announce that Krzysztof Cwalina has a guideline ready for you to comment on!

System.URI Usage

Use System.Uri to represent URI/URL data. This applies to parameter types, property types, and return value types.

public class Navigator {

public Navigator(Uri initialLocation);

public Uri CurrentLocation { get; }

public Uri NavigateTo(Uri location);

}

Note: System.Uri is a much safer and richer way of representing URIs. Extensive manipulation of URI related data using plain strings has been shown to cause many security and correctness problems. An excellent whitepaper describing the issues in more details is on it's way

Consider providing string-based overloads for most commonly used members with System.Uri parameters.

In cases where the usage pattern of taking a string from a user will be common enough, you should consider adding a convenience overload accepting a string. The string-based overload should be implemented in terms of the Uri-based overload.

public class Navigator {

public void NavigateTo(Uri location);
public void NavigateTo(string location) {

NavigateTo (new Uri (location));

}
}

Do not automatically overload all Uri-based members with a version that accepts a string.

Generally, Uri-based APIs are preferred. String-based overloads are meant to be helpers for the most common scenarios. Therefore, you should not automatically provide string-based overloads for all variants of the Uri-based members. Be selective and provide such helpers just for the most commonly used variants.

public class Navigator {

public void NavigateTo(Uri location);

public void NavigateTo(string location);
public void NavigateTo(Uri location, NavigationMode mode);
}

1.1.1 URI/URL Data Implementation Rules

Call the Uri-based overloads if available.

Do not store URI/URL data in a string.

When you accept a URI/URL input as a string, you should convert the string to a System.Uri and store the instance of System.Uri.

In addition here are the FxCop rules we are thinking about to help enforce this guideline:

If a parameter name contains “uri” or “url” or “urn” and it’s typed as string, the parameter type should be changed to System.Uri, unless there is an overload method where the same parameter is types as Uri.

If a function name contains “uri” or “url” or “urn” and the return type is string, the return type should be changed to System.Uri.

If a property name contains “uri” or “url” or “urn” and it’s typed as string, it should be changed to System.Uri.

If a parameter is typed as System.Uri and the member has an overload where a parameter at the same position is typed as System.String, the member should not do anything with the string except to pass it to Uri.TryParse or Uri.ctor, and call the overload that takes Uri.

If there are two overloads one taking System.Uri and one taking System.String, library code should never call the string-based overload.

Design Guidelines Update: Enums vs Boolean Arguments

BradA — Mon, 12 Jan 2004 18:01:00 GMT

This was a pretty heavily debated guideline internally, I think we reached a good conclusion... Your feedback welcome as always!

The full guidelines can be found here, we will be roll this (and other updates) into it for the whidbey release.

Enums vs Boolean Arguments

A framework designer is often faced with the choice of when to use enums and when to use Booleans for method and constructor arguments. In general terms you should favor using enums where it makes the readability of source code more explicit and therefore easier to understand. Anywhere using enums would add unneeded complexity and actually hurt readability of source code Booleans should be preferred.

Do use enums if you two or more arguments that are Booleans.

Enums are much more readable (in books, documentation, code reviews, etc). Consider a method call that looks such as:

FileStream f = File.Open (“foo.txt”, true, false);

This call gives you no context whatsoever to understand the meaning behind true and false. Now consider if the call where:

FileStream f = File.Open (“foo.txt”, CasingOptions.CaseSenstative, FileMode.Open);

Annotation: Some have asked why we don’t have a similar guideline for integers, doubles, etc, should we find a way to “name” them as well? There is a big difference between numeric types and Booleans: you almost always use constants and variables to pass numerics around, because it is good programming practice and you don’t want to have “magic numbers”. However, if you take a look at any managed code-base, this is almost never true of Booleans. 80% of the time a Boolean argument is passed in as a constant, and its intention is to turn a piece of behavior on or off. We could alternatively try to establish a coding guideline that you should never pass a primitive “true/false” value to a method or constructor, but we would probably get significant pushback on that. I certainly don’t want to define a constant for each Boolean parameter I’m passing in.

Enums are much easier for developers to work with in Intellisense and in documentation. Often a good parameter name can give you a hint as to when to pass true or false, but parameter names are not generally available when reading code. enums leave little ambiguity by making very clear which value to pass when writing and reading code.

Annotation: Methods with two Boolean parameters (like the one in the example above) allow developers to inadvertently switch the arguments, and the compiler and static analysis tools can't help you. Even with just one parameter, I tend to believe it's a somewhat easier to make a mistake with Booleans ... let's see, does true mean "case insensitive" or "case sensitive"?

Do use enums unless you are 100% sure there will never be a need for another option.

Enums have the potential to give you more room for future expansion but be aware of versioning issues specific to enums in section x.y.

Annotation: We have seen a couple of places in the framework where we added a Boolean in V1 and in V2 we were forced to add another Boolean option to account for what could have been a foreseeable change. Don’t let this happen to you, if there is even a slight possibility of needing a more options in the future use an enum now.

Avoid using enums for method\constructor arguments for single arguments that are truly two state values. If the member does not take more than one Boolean argument and there are now and forever more only two states.

Annotation: There are a number of reasons to avoid introduction of more enums than necessary to meet the spirit of this guideline. Most of the problems manifest themselves when you use properties that return Enums which is not directly covered by this guideline. Examples include:

It is difficult to “interop” what are essentially Boolean values that are expressed as independent enums. For instance, if I want to do something like underline something that is not bold, I want to be able to do the following:

myStyle.Underline = !myStyle.Bold;

This works because both underline and bold are two-state, and will always be two-state (there are always examples where this is not the case, and in such cases, enums should be used). Note that if I were to use enums, I’d need to write:

if (myStyle.Boldness == BoldStyle.Bold)

{

myStyle.Underline = UnderlineStyle.NoUnderline;

}

else

{

myStyle.Underline = UnderlineStyle.Underline;

}

myStyle.Underline =

(myStile.Boldness == BoldStyle.Bold ? UnderlineStyle.NoUnderline : UnderlineStyle.Underline);

neither of which are particularly appealing.

If the enum is returned from a property, then the consumer of that property doesn’t really know whether or not they need to consider whether or not the enum is going to have additional states in later versions. They don’t know that it’s now and forevermore a two-state value. Therefore, they don’t know what to do in the “default” section of their switch statement that consumes this value. As an example of this, the writer of the code in the point above may not know that BoldStyle is truly and forevermore a two-state value. To protect themselves for versioning’s sake, they won’t even be able to write the above, they’ll need to go even further to:

switch (myStyle.Boldness)

{

case BoldStyle.Bold:

myStyle.Underline = UnderlineStyle.NoUnderline;

break;

case BoldStyle.NotBold:

myStyle.Underline = UnderlineStyle.Underline;

break;

default:

// something else, appropriate for versioning of this code.

break;

}

As an even more extreme, but very real, example of the issue described at top, consider the databinding scenario where one wants to databind two values that would otherwise be Booleans together. For example, binding the “bold-ness” of one instance to the “underline-ness” of another. Here, the problem is exacerbated because writing the code that would do the conversion between enum values is much less simple… that is, there’s typically not a chunk of code to add such a conversion into. What is required is the addition of a data transformer into the data binding evaluation that will do the transformation. Same problem and issue, just a much more elaborate workaround required.

Hence, because of these difficulties in using enums when Booleans sufficiently describe the data, API designers should think hard about whether they really require multiple Boolean parameters to a method. If they can avoid such method signatures, they should be able to avoid introducing a new enum when a Boolean will do.

Annotation: An interesting clarification of this guideline for constructor parameters that map onto properties is that if the value is typically set in the constructor an enum value is better otherwise a Boolean value is better. This thinking helped us clarify a recent CodeDom work item to add “IsGlobal” on CodeTypeReference. In this case it should be an enum because it is typically set in the constructor, but the “IsPartial” property on CodeTypeDeclaration should be a Boolean.

Avoid sharing of enum types between different families of methods. Although it may seem like similar concepts unless there represent the exact same concept there will be issues as they diverge in the future.

Annotation: Generally speaking, enums don’t cost noticeably more than Booleans. As far as the runtime is considered an enum is treated just like its underlying type which is in most cases Int32 (the same in memory size Booleans take up). Today there is a very small overhead (on the order of 300 bytes for each enum type referenced) but this at the noise range and should not be considered a factor in choosing to use a Boolean over an enum.

It is possible to write bad code with enums that does perform poorly; you should see section x.y on argument validation for a note on avoiding calls to Enum.IsDefined as it loads reflection which is often performance issue.

Design Guidelines Update: "Core" Method pattern

BradA — Fri, 19 Dec 2003 00:10:00 GMT

Minor tweaks to this guideline to line up with what is, I believe, common practice already..

As always questions, comments and annotations to me, and the full guidelines can be found here: http://www.gotdotnet.com/team/libraries

----------

It is recommended that you provide customization through protected (family) methods.

The public interface of a base class should provide a rich set of functionality for the consumer of that class. However, customizers of that class often want to implement the fewest methods possible to provide that rich set of functionality to the consumer. To meet this goal, provide a set of non-virtual or final public methods that call through to a single (or very small set of) protected (family) method with the “Core” suffix that provides implementations for such a method.

public Control{
//…
public void SetBounds(int x, int y, int width, int height){

      …
      SetBoundsCore (…);
   }

public void SetBounds(int x, int y, int width, int

height, BoundsSpecified specified){

       …
       SetBoundsCore (…);
   }

protected virtual void SetBoundsCore(int x, int y, int width, int

      height, BoundsSpecified specified){
         // Do the real work here.
      }
   }

Annotation (BradA): Notice in a few parts of the Framework v1.0 we used the suffix “Impl” for this convention. In retrospect “Core” is more common and is not an abbreviation, so we choice to standardize on it.