5.1.1 Member Overloading

Member overloading means creating two or more members on the same type that differ only in the number or type of parameters but have the same name. For example, in the following, the WriteLine method is overloaded:

Click here to view code image

public static class Console {
  public void WriteLine();
  public void WriteLine(string value);
  public void WriteLine(bool value);
  ...
}

Because only methods, constructors, and indexed properties can have parameters, only those members can be overloaded.

Overloading is one of the most important techniques for improving the usability, productivity, and readability of reusable libraries. Overloading on the number of parameters makes it possible to provide simpler versions of constructors and methods. Overloading on the parameter type makes it possible to use the same member name for members performing identical operations on a selected set of different types.

For example, System.DateTime has several constructor overloads. The most powerful—but also the most complex—one takes eight parameters. Thanks to constructor overloading, the type also supports a shortened constructor that takes only three simple parameters: hours, minutes, and seconds.

Click here to view code image

public struct DateTime {
  public DateTime(int year, int month, int day,
            int hour, int minute, int second,
            int millisecond, Calendar calendar) { ... }

  public DateTime(int hour, int minute, int second) { ... }
}

This section does not cover the similarly named but quite different construct called operator overloading. Operator overloading is described in section 5.7.

DO try to use descriptive parameter names to indicate the default used by shorter overloads.

In a family of members overloaded on the number of parameters, the longer overload should use parameter names that indicate the default value used by the corresponding shorter member. This is mostly applicable to Boolean parameters. For example, in the following code, the first short overload does a case-sensitive look-up. The second, longer overload adds a Boolean parameter that controls whether the look-up is case sensitive. The parameter is named ignoreCase rather than caseSensitive to indicate that the longer overload should be used to ignore case and that the shorter overload probably defaults to the opposite, a case-sensitive look-up.

Click here to view code image

public class Type {
  public MethodInfo GetMethod(string name); //ignoreCase = false
  public MethodInfo GetMethod(string name, Boolean ignoreCase);
}

DO NOT arbitrarily vary parameter names in overloads. If a parameter in one overload represents the same input as a parameter in another overload, the parameters should have the same name.

Click here to view code image

public class String {
   // correct
   public int IndexOf (string value) { ... }
   public int IndexOf (string value, int startIndex) { ... }

   // incorrect
   public int IndexOf (string value) { ... }
   public int IndexOf (string str, int startIndex) { ... }
}

AVOID being inconsistent in the ordering of parameters in overloaded members. Parameters with the same name should appear in the same position in all overloads.

Click here to view code image

public class EventLog {
   public EventLog();
   public EventLog(string logName);
   public EventLog(string logName, string machineName);
   public EventLog(string logName, string machineName, string source);
}

In some specific cases, this otherwise very strict guideline can be broken. For example, a params array parameter has to be the last parameter in a parameter list. If a params array parameter appears in an overloaded member, the API designer might need to make a trade-off and either settle for inconsistent parameter ordering or not use the params modifier. For more information on the params array parameters, see section 5.8.4.

Another case where the guideline might need to be violated is when the parameter list contains out parameters. These parameters should typically appear at the end of the parameter list, which again means that the API designer might need to settle for a slightly inconsistent order of parameters in overloads with out parameters. See section 5.8 for more information on out parameters.

DO make only the longest overload virtual (if extensibility is required). Shorter overloads should simply call through to a longer overload.

Click here to view code image

public class Encoding {
   public bool IsAlwaysNormalized(){
     return IsAlwaysNormalized(NormalizationForm.FormC);
   }
   public virtual bool IsAlwaysNormalized(NormalizationForm form){
     //do real work here
   }
}

For more information on the design of virtual members, see Chapter 6.

DO NOT use ref, out, or in modifiers to overload members.

For example, you should not do the following:

Click here to view code image

public class SomeType {
  public void SomeMethod(string name){ ... }
  public void SomeMethod(out string name){ ... }
}

Some languages cannot resolve calls to overloads like this. In addition, such overloads usually have completely different semantics and probably should not be overloads at all, but rather two separate methods.

DO NOT have overloads with parameters at the same position and similar types, yet with different semantics.

The following example is a bit extreme, but it does illustrate the point:

Click here to view code image

public class SomeType {
  public void Print(long value, string terminator){
    Console.Write("{ʘ}{1}",value,terminator);
  }
  public void Print(int repetitions, string str){
    for(int i=ʘ; i< repetitions; i++){
        Console.Write(str);
    }
  }
}

The methods just presented should not be overloads. They should have two different names.

It’s difficult in some languages (in particular, dynamically typed languages) to resolve calls to these kinds of overloads. In most cases, if two overloads called with a number and a string would do exactly the same thing, it would not matter which overload is called. For example, the following is fine, because these methods are semantically equivalent:

Click here to view code image

public static class Console {
  public void WriteLine(long value){ ... }
  public void WriteLine(int value){ ... }
}

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 that the default value should be used. This avoids the problem of having to check for null before calling an API, as shown here:

Click here to view code image

if (geometry==null) DrawGeometry(brush, pen);
else DrawGeometry(brush, pen, geometry);

DO NOT have overloads with a generic type parameter in one method and a specific type in another.

When designing methods on a generic type, it may sometimes seem appropriate to have a generic-based overload and a System.String-based overload, as in this example:

Click here to view code image

public class PrettyPrinter<T> {
  public void PrettyPrint(string format){ ... }
  public void PrettyPrint(T otherPrinter){ ... }
  public void PrettyPrint(T otherPrinter, string format){ ... }
}

However, when the generic type is itself System.String, the overload that uses the generic type parameter becomes uncallable.

Click here to view code image

PrettyPrinter<string> printer = new PrettyPrinter<string>();
...
// C# overload resolution says this is PrettyPrint(string),
// not PrettyPrint(T).
// There's no way to call PrettyPrint(T) from C#.
printer.PrettyPrint("hello, world");

CONSIDER using default parameters on the longest overload of a method.

Default parameters are available in C#, F#, and VB.NET, but they are not CLS-compliant and may not be well supported by all languages that can use .NET libraries.

For the languages that do support default parameters, the use of default parameters can reduce the number of overloads that becomes possible for expressing every combination of optional parameters while still allowing the caller to use a somewhat minimal method invocation.

Click here to view code image

public static BigInteger Parse(
   ReadOnlySpan<char> value,
   NumberStyles style = NumberStyles.Integer,
   IFormatProvider provider = null) { ... }
...
BigInteger val = BigInteger.Parse(input, provider: formatCulture);

DO provide a simple overload, with no default parameters, for any method with two or more defaulted parameters.

Usability studies have shown that default parameters are a comparatively advanced feature. Many developers are confused with the presentation in IntelliSense, and sometimes think that they have to provide the defaulted arguments as exactly the value shown by IntelliSense. Providing the simple overload makes your method easier to approach for users who need only the default behaviors.

Click here to view code image

public static BigInteger Parse(ReadOnlySpan<char> value)
   // Since a provider is 'specified' this calls the overload
   // which uses default parameters.
   => Parse(value, provider: null);

public static BigInteger Parse(
   ReadOnlySpan<char> value,
   NumberStyles style = NumberStyles.Integer,
   IFormatProvider provider = null) { ... }

DO NOT use default parameters, for any parameter type other than CancellationToken, on interface methods or virtual methods on classes.

A disagreement between an interface declaration and the implementation on a default value creates an unnecessary source of confusion for your users. The same confusion also arises when a virtual method and an override of that method disagree on the default values for a parameter. The most straightforward solution to this problem is to avoid the situation, and only use default parameters on nonvirtual methods.

CancellationToken is specifically exempted from this guideline, because the guidance for asynchronous methods (section 9.2) is to always have a CancellationToken parameter with a default value. Since there’s only one legal default value for a CancellationToken— that is, default(CancellationToken)—no default value disagreement is possible between implementations.

Click here to view code image

public interface IExample {
 void PrintValue(int value = 5);
}

public class Example : IExample {
 public virtual void PrintValue(int value = 1ʘ) {
   Console.WriteLine(value);
 }
}
public class DerivedExample : Example {
 public override void PrintValue(int value = 2ʘ) {
   base.PrintValue(value);
 }
}

...

// What gets printed?
// If you have to think about it, the API is not self-documenting.
DerivedExample derived = new DerivedExample();
Example e = derived;
IExample ie = derived;
derived.PrintValue();
e.PrintValue();
ie.PrintValue();

For types that use the Template Method Pattern (section 9.9), the longest overload of the public nonvirtual method can use default parameters when appropriate, then defer to the virtual implementation method without using default parameters.

Click here to view code image

public partial class Control {
 // The public method uses a default parameter
 public void SetBounds(
   int x,
   int y,
   int width,
   int height,
   BoundsSpecified specified = BoundsSpecified.All) {
   ...
   SetBoundsCore(x, y, width, height, specified);
 }

 // The protected (virtual) method does not use default parameters
 protected virtual void SetBoundsCore(
   int x,
   int y,
   int width,
   int height,
   BoundsSpecified specified) {
   // Do the real work here.
 }
}

Default parameters can be provided for interface methods via extension methods.

Click here to view code image

public interface IExample {
 void PrintValue(int value);
}

public static class ExampleExtensions : IExample {
 public static void PrintValue(
   this IExample example,
   int value = 1ʘ) {

   // While this may look like a recursive call,
   // the C# method resolution rules say the instance member
   // from the interface is a better match than this extension
   // method.
   example.PrintValue(value);
 }

One proposed alternative to not using default parameters in virtual methods was to say that virtual overrides should always match the defaults from the original method declaration. However, that guideline leads to versioning problems when derived types exist in a different assembly:

• Changing the last required parameter of a method to be a default parameter is generally not a breaking change, but would cause the override to provide a different set of defaults.

• The guidance for adding a new default parameter to an existing method (provided next) calls for removing the defaults from the current method overload, which can result in ambiguous method compile-time failures due to the overrides that have yet to be updated.

DO NOT change the default value for a parameter once it has been publicly released.

Default parameters do not create logical overloads in the assembly that defines them, but are just a convenience mechanism to enable the compiler to fill in any missing values for the calling code at compile-time. When the value changes between two releases of a library, any existing callers will use the old value until they recompile, at which point they will switch to the new value. This can lead to confusion when diagnosing issues raised by users, when their reproduction cases don’t exhibit the bad behavior due to the changed default value.

If you want to be able to change the value over time, use an otherwise illegal sentinel value such as zero or -1 to indicate the runtime default value should be used instead.

Click here to view code image

// In this method, the style parameter should continue to use
// NumberStyles.Integer in all future versions of the library.
//
// Since the provider parameter has a default value of null,
// the library can change the default as an implementation detail
// (assuming that's an acceptable breaking change for the method).
public static BigInteger Parse(
   ReadOnlySpan<char> value,
   NumberStyles style = NumberStyles.Integer,
   IFormatProvider provider = null) { ... }

DO NOT have two overloads of a method with “compatible” required parameters that both use default parameters.

AVOID having two overloads of the same method that both use default parameters.

DO NOT have different defaults for the same parameter in two overloads of the same method.

The only time that two overloads of the same method should both have default parameters is when their required parameters have incompatible signatures. The parameters shared in common by the two overloads should have the same default values, or no default value. This makes it abundantly clear which overload is being called.

Click here to view code image

// Given this overload already exists
public static OperationStatus DecodeFromUtf8(
 ReadOnlySpan<byte> utf8,
 Span<byte> bytes,
 out int bytesConsumed,
 out int bytesWritten,
 bool isFinalBlock = true) { ... }

// OK: default parameters have the same value,
// and the signatures are incompatible
public static byte[] DecodeFromUtf8(
 byte[] utf8,
 out int bytesConsumed,
 bool isFinalBlock = true) { ... }

// BAD: default parameters have a different value
public static byte[] DecodeFromUtf8(
 byte[] utf8,
 out int bytesConsumed,
 bool isFinalBlock = false) { ... }

// BAD: This longer overload's required parameters are compatible
// with the original overload
public static OperationStatus DecodeFromUtf8(
 ReadOnlySpan<byte> utf8,
 Span<byte> bytes,
 out int bytesConsumed,
 out int bytesWritten,
 bool isFinalBlock = true,
 int bufferSize = 512) { ... }

DO move all default parameters to the new, longer overload when adding optional parameters to an existing method.

In the previous example, when adding the bufferSize parameter, the existing DecodeFromUtf8 method should change to no longer have a default value for the isFinalBlock parameter when the new overload is added. This method cannot be deleted without introducing a runtime breaking change (a MissingMethodException) in upgrade scenarios. Since having a simple parameter after an out parameter makes this DecodeFromUtf8 overload no longer conform to design guidelines, it is advisable to attribute it as [EditorBrowsable(EditorBrowsableState.Never)]. IntelliSense will only show the new overload with the additional optional parameters.

Click here to view code image

// This overload no longer has a default value for isFinalBlock,
// and has been marked as hidden from IntelliSense.
[EditorBrowsable(EditorBrowsableState.Never)]
public static OperationStatus DecodeFromUtf8(
 ReadOnlySpan<byte> utf8,
 Span<byte> bytes,
 out int bytesConsumed,
 out int bytesWritten,
 bool isFinalBlock) { /* call the longer overload */ }

public static OperationStatus DecodeFromUtf8(
 ReadOnlySpan<byte> utf8,
 Span<byte> bytes,
 out int bytesConsumed,
 out int bytesWritten,
 bool isFinalBlock = true,
 int bufferSize = 512) { ... }

5.1.2 Implementing Interface Members Explicitly

Explicit interface member implementation allows an interface member to be implemented so that it is only callable when the instance is cast to the interface type. For example, consider the following definition:

Click here to view code image

public struct Int32 : IConvertible {
  int IConvertible.ToInt32 () {..}
   ...
}

// calling ToInt32 defined on Int32
int i = ʘ;
i.ToInt32(); // does not compile
((IConvertible)i).ToInt32(); // works just fine

In general, implementing interface members explicitly is straightforward and follows the same general guidelines as those for methods, properties, or events. However, some specific guidelines apply to implementing interface members explicitly, as described next.

AVOID implementing interface members explicitly without having a strong reason to do so.

Explicitly implemented members can be confusing to developers because such members don’t appear in the list of public members and can also cause unnecessary boxing of value types.

public int CallToInt32<T>(T convertible) where T : IConvertible =>
   convertible.ToInt32();

class Collection : IEnumerable {
  IEnumerator IEnumerable.GetEnumerator() { ... }
  public MyEnumerator GetEnumerator() { ... }
}

CONSIDER implementing interface members explicitly if the members are intended to be called only through the interface.

This includes mainly members supporting framework infrastructure, such as data binding or serialization. For example, ICollection<T>. IsReadOnly is intended to be accessed mainly by the data-binding infrastructure through the ICollection<T> interface. It is almost never accessed directly when using types implementing the interface. Therefore, List<T> implements the member explicitly.

CONSIDER implementing interface members explicitly to simulate variance (change parameters or return types in “overridden” members).

For example, IList implementations often change the type of the parameters and returned values to create strongly typed collections by explicitly implementing (hiding) the loosely typed member and adding the publicly implemented strongly typed member.

Click here to view code image

public class StringCollection : IList {
  public string this[int index]{ ... }
  object IList.this[int index] { ... }
  ...
}

CONSIDER implementing interface members explicitly to hide a member and add an equivalent member with a better name.

You can say that this amounts to renaming a member. For example, System.Collections.Concurrent.ConcurrentQueue<T> implements IProducerConsumerCollection<T>.TryTake explicitly and renames it to TryDequeue.

Click here to view code image

partial class ConcurrentQueue<T> : IProducerConsumerCollection<T> {
  bool IProducerConsumerCollection<T>.TryTake(out T item) =>
    TryDequeue(out item);

  public bool TryDequeue(out T result) { ... }
}

Such member renaming should be done extremely sparingly. In most cases, the added confusion is a bigger problem than the suboptimal name of the interface member.

DO NOT use explicit members as a security boundary.

Such members can be called by any code by simply casting an instance to the interface.

DO provide a protected virtual member that offers the same functionality as the explicitly implemented member if the functionality is meant to be specialized by derived classes.

Explicitly implemented members cannot be overridden. They can be redefined, but then subtypes cannot call the base method’s implementation. It is recommended that you name the protected member by either using the same name or affixing Core to the interface member name.

Click here to view code image

[Serializable]
public class List<T> : ISerializable {
  ...
   void ISerializable.GetObjectData(
    SerializationInfo info, StreamingContext context) {
    GetObjectData(info,context);
   }

   protected virtual void GetObjectData(
    SerializationInfo info, StreamingContext context) {
    ...
   }
}

5.1.3 Choosing Between Properties and Methods

When designing members of a type, one of the most common decisions a library designer must make is to choose whether a member should be a property or a method.

On a high level, there are two general styles of API design in terms of usage of properties and methods. In method-heavy APIs, methods have a large number of parameters, and the types have fewer properties.

Click here to view code image

public class PersonFinder {
  public string FindPersonsName (
    int height,
    int weight,
    string hairColor,
    string eyeColor,
    int shoeSize,
    Connection database
  );
}

In property-heavy APIs, methods have a small number of parameters and more properties to control the semantics of the methods.

Click here to view code image

public class PersonFinder {
  public int Height { get; set; }
  public int Weight { get; set; }
  public string HairColor { get;set; }
  public string EyeColor { get; set; }
  public int ShoeSize { get; set; }

  public string FindPersonsName (Connection database);
}

All else being equal, the property-heavy design is generally preferable because methods with many parameters are less approachable to inexperienced developers. This is described in detail in Chapter 2.

Another reason to use properties when they are appropriate is that property values show up automatically in the debugger. By comparison, inspecting a value of a method is much more cumbersome.

However, it is worth noting that the method-heavy design has the advantage in terms of performance, and might result in better APIs for advanced users.

A rule of thumb is that methods should represent actions and properties should represent data. Properties are preferred over methods if everything else is equal.

CONSIDER using a property if the member represents a logical attribute of the type.

For example, Button.Color is a property because color is an attribute of a button.

DO use a property, rather than a method, if the value of the property is stored in the process memory and the property would just provide access to the value.

For example, a member that retrieves the name of a Customer from a field stored in the object should be a property.

Click here to view code image

public Customer {
  public Customer(string name){
    this.name = name;
  }
   public string Name {
    get { return this.name; }
  }
  private string name;
}

DO use a method, rather than a property, in the following situations:

• The operation is orders of magnitude slower than a field access would be. If you are even considering providing an asynchronous version of an operation to avoid blocking the thread, it is very likely that the operation is too expensive to be a property. In particular, operations that access the network or the file system (other than once for initialization) should likely be methods, not properties.

• The operation is a conversion, such as the Object.ToString method.

• The operation returns a different result each time it is called, even if the parameters don’t change. For example, the Guid.NewGuid method returns a different value each time it is called.

  Jeffrey Richter

  The DateTime.Now property is an example of a place in .NET where this property should have been a method because the operation returns a different result each time.

• The operation has a significant and observable side effect. Notice that populating an internal cache is not generally considered an observable side effect.

  Brian Pepin

  The Handle property on a Windows Forms control is an example of where too many side effects might occur. If the control has not had its handle created yet, accessing the Handle property will create it. I can’t tell you how many times I’ve completely changed the result of a debugging session by setting up a watch on the Handle property. The debugger’s watch will actually create the control’s handle, often hiding your bug.

• The operation returns a copy of an internal state (this does not include copies of value-type objects returned on the stack).

• The operation returns an array.

Properties that return arrays can be very misleading. Usually it is necessary to return a copy of an internal array so that the user cannot change the internal state. This could lead to inefficient code.

In the following example, the Employees property is accessed twice in every iteration of the loop. That would be 2n + 1 copies for the following short code sample:

Click here to view code image

Company microsoft = GetCompanyData("MSFT");
for (int i = ʘ; i < microsoft.Employees.Length; i++) {
   if (microsoft.Employees[i].Alias == "kcwalina"){
       ...
   }
}

This problem can be addressed in one of two ways:

• Change the property into a method, which communicates to callers that they are not just accessing an internal field and probably are creating an array every time they call the method. Given that, users are more likely to call the method once, cache the result, and work with the cached array.

  Click here to view code image

  Company microsoft = GetCompanyData("MSFT");
  Employees[] employees = microsoft.GetEmployees();
  for (int i = ʘ; i < employees.Length; i++) {
     if (employees[i].Alias == "kcwalina"){
         ...
     }
  }

• Change the property to return a collection instead of an array. You can use ReadOnlyCollection<T> to provide public read-only access to a private array. Alternatively, you can use a subclass of Collection<T> to provide controlled read-write access, so that you can be notified when the user code modifies the collection. See section 8.3 for more details on using ReadOnlyCollection<T> and Collection<T>.

  Click here to view code image

  public ReadOnlyCollection<Employee> Employees {
     get { return roEmployees; }
  }
  private Employee[] employees;
  private ReadOnlyCollection<Employee> roEmployees;

5.2.1 Indexed Property Design

An indexed property is a special property that can have parameters and can be called with special syntax similar to array indexing.

Click here to view code image

public class String {
  public char this[int index] {
    get { ... }
  }
}
...

string city = "Seattle";
Console.WriteLine(city[0]); // this will print 'S'

Indexed properties are commonly referred to as indexers. Indexers should be used only in APIs that provide access to items in a logical collection. For example, a string is a collection of characters, and the indexer on System.String exists to access its characters.

CONSIDER using indexers to provide access to data stored in an internal array.

CONSIDER providing indexers on types representing collections of items.

AVOID using indexed properties with more than one parameter.

If the design requires multiple parameters, reconsider whether the property really represents an accessor to a logical collection. If it does not, use methods instead. Consider starting the method name with Get or Set.

AVOID indexers with parameter types other than System.Int32, System.Int64, System.String, System.Range, System.Index, or an enum, except on dictionary-like types.

If the design requires other types of parameters, strongly reevaluate whether the API really represents an accessor to a logical collection. If it does not, use a method. Consider starting the method name with Get or Set.

DO use the name Item for indexed properties unless there is an obviously better name (e.g., see the Chars property on System.String).

In C#, indexers are by default named Item. The IndexerNameAttribute can be used to customize this name.

Click here to view code image

public sealed class String {
 [System.Runtime.CompilerServices.IndexerNameAttribute("Chars")]
 public char this[int index] {
   get { ... }
 }
 ...
}

DO NOT provide both an indexer and methods that are semantically equivalent.

In the following example, the indexer should be changed to a method.

Click here to view code image

// Bad design
public class Type {
  [System.Runtime.CompilerServices.IndexerNameAttribute("Members")]
  public MemberInfo this[string memberName]{ ... }
  public MemberInfo GetMember(string memberName, Boolean ignoreCase){
... }
}

DO NOT provide more than one family of overloaded indexers in one type.

This is enforced by the C# compiler.

DO NOT use nondefault indexed properties.

This is enforced by the C# compiler.

DO return the declaring type from an indexer that accepts System.Range.

Range-based indexers on a collection should return a collection of the same type as the type that declares them. This includes implicit indexers created by having a Slice method with the appropriate signature. Instead of violating this guideline when your goal is to create a different type, provide a separate conversion method. For example, arrays produce a copy of the requested range in the Range indexer, but arrays also have the array.AsSpan(Range) extension method to produce a Span<T> for the same range of indices.

Click here to view code image

// OK: Returns the declaring type from a Range-based indexer
public partial class SomeCollection {
  public SomeCollection this[Range range] { get { ... } }
}

// OK: Returns the declaring type from Slice(int, int), which
// makes an implicit indexer in C#
public partial class SomeCollection {
  public SomeCollection Slice(int offset, int length) { ... }
}

// BAD: Returns the wrong type from a Range-based indexer
public partial class SomeCollection {
  public SomeValue[] this[Range range] { get { ... } }
}

// BAD: Returns the wrong type from Slice(int, int), which
// makes an implicit indexer in C#
public partial class SomeCollection {
  public SomeValue[] Slice(int offset, int length) { ... }
}

5.2.2 Property Change Notification Events

Sometimes it is useful to provide an event notifying the user of changes in a property value. For example, System.Windows.Forms.Control raises a TextChanged event after the value of its Text property has changed.

Click here to view code image

public class Control : Component{
  string text = String.Empty;

  public event EventHandler<EventArgs> TextChanged;
  public string Text{
     get{ return text; }
     set{
       if (text!=value) {
           text = value;
           OnTextChanged();
       }
     }
 }

 protected virtual void OnTextChanged(){
    EventHandler<EventArgs> handler = TextChanged;
    if(handler!=null){
      handler(this,EventArgs.Empty);
    }
  }
}

The guidelines that follow describe when property change events are appropriate and their recommended design for these APIs.

CONSIDER raising change notification events when property values in high-level APIs (usually designer components) are modified.

If there is a good scenario for a user to know when a property of an object is changing, the object should raise a change notification event for the property.

However, it is unlikely to be worth the overhead to raise such events for low-level APIs such as base types or collections. For example, List<T> would not raise such events when a new item is added to the list and the Count property changes.

CONSIDER raising change notification events when the value of a property changes via external forces.

If a property value changes via some external force (in a way other than by calling methods on the object), raising events indicates to the developer that the value is changing or has changed. A good example is the Text property of a text box control. When the user types text in a TextBox, the property value automatically changes.

5.3.1 Type Constructor Guidelines

A type constructor, also called a static constructor, is used to initialize a type. The runtime calls the static constructor before the first instance of the type is created or any static members of the type are accessed.

DO make static constructors private.

A static constructor, also called a class constructor, is used to initialize a type. The CLR calls the static constructor before the first instance of the type is created or any static members of that type are called. The user has no control over when the static constructor is called. If a static constructor is not private, it can be called by code other than the CLR. Depending on the operations performed in the constructor, this can cause unexpected behavior.

The C# compiler forces static constructors to be private.

DO NOT throw exceptions from static constructors.

If an exception is thrown from a type constructor, the type is not usable in the current application domain.

using System.Threading;

class Test
{
   static void Main() { }

   static Test()
   {
      var t = new Thread(ThreadStart);
      t.Start();
      t.Join();
   }

   static void ThreadStart() { }
}

CONSIDER initializing static fields inline rather than explicitly using static constructors, because the runtime is able to optimize the performance of types that don’t have an explicitly defined static constructor.

Click here to view code image

// unoptimized code
public class Foo {
  public static readonly int Value;
  static Foo() {
    Value = 63;
  }
  public static void PrintValue() {
    Console.WriteLine(Value);
  }
}

// optimized code
public class Foo {
  public static readonly int Value = 63;
  public static void PrintValue() {
     Console.WriteLine(Value);
  }
}

5.7.1 Overloading Operator ==

Overloading operator == is quite complicated. The semantics of the operator need to be compatible with several other members, such as Object.Equals. For more information on this subject, see sections 8.9.1 and 8.13.

5.7.2 Conversion Operators

Conversion operators are unary operators that allow conversion from one type to another. The operators must be defined as static members on either the operand or the return type. There are two types of conversion operators: implicit and explicit.

Click here to view code image

public struct RangedInt32 {
  public static implicit operator int(RangedInt32 value){ ... }
  public static explicit operator RangedInt32(int value) { ... }
  ...
}

DO NOT provide a conversion operator if such a conversion is not clearly expected by the end users.

Ideally, you should have some user research data showing that the conversion is expected, or some prior art examples where a similar type needed such conversion.

DO NOT define conversion operators outside of a type’s domain.

For example, Int32, Int64, Double, and Decimal are all numeric types, whereas DateTime is not. Therefore, there should be no conversion operator to convert Int64 (long) to a DateTime. A constructor is preferred in such a case.

Click here to view code image

public struct DateTime {
  public DateTime(long ticks){ ... }
}

DO NOT provide an implicit conversion operator if the conversion is potentially lossy.

For example, there should not be an implicit conversion from Double to Int32 because Double has a wider range than Int32. An explicit conversion operator can be provided even if the conversion is potentially lossy.

DO NOT provide an implicit conversion operator if the conversion requires nontrivial work.

Since implicit conversions are usually not visible in calling code, the potential performance costs of the method will be hidden from anyone reading the code. If a conversion requires more than a small amount of constant-time work, it should instead be exposed as a named method.

DO NOT throw exceptions from implicit conversion operators.

It is very difficult for end users to understand what is happening, because they might not be aware that a conversion is taking place.

DO throw System.InvalidCastException if a call to a cast operator results in a lossy conversion and the contract of the operator does not allow lossy conversions.

Click here to view code image

public static explicit operator RangedInt32(long value) {
  if (value < Int32.MinValue || value > Int32.MaxValue) {
      throw new InvalidCastException();
   }
   return new RangedInt32((int)value, Int32.MinValue, Int32.MaxValue);
}

5.7.3 Inequality Operators

The inequality operators (<, <=, >, >=) allow for concise mathematical expressions to be written in code. The use of these operators on custom types should be consistent with the built-in operators. The strict inequality operator (!=) is specifically associated with the equality operator (==), discussed in section 8.13.

DO only implement inequality operators on types that implement IComparable<T>.

DO implement inequality operators consistent with the IComparable<T> implementation.

Because IComparable<T> and the inequality operators are performing similar roles, anything defining the operators automatically has an easy basis for implementing the interface.

Click here to view code image

public static bool operator <(SomeType left, SomeType right) =>
   left.CompareTo(right) < ʘ;

DO implement operator <= on types that implement operator < and IEquatable<T>.

When both “less than” and “equal” are defined, then “less than or equal” should be well defined.

DO return a Boolean value from custom inequality operators.

DO define inequality operators consistent with their mathematical properties.

Custom inequality operators should all behave as they do on built-in numeric types:

• The transitive property: If a < b and b < c, then a < c.

• The reversal property: If a < b, then b > a.

• The irreflexive property: If a < a is false, then a > a is false.

• The asymmetric property: If a < b is true, then b < a is false.

Following this guideline allows developers using your operators to write code, and their reviewers to read it, and apply the same logical analysis they would to your type as they would to the built-in numeric types.

Using the inequality operators for a projective map, or for any purpose other than Boolean mathematical comparisons, makes code harder to reason about.

Click here to view code image

// Almost everyone believes that the type of x here is Boolean.
// Therefore it should be for any inequality operator you define.
var x = a < b;

AVOID defining inequality operators against different types.

The reversal property of inequality says that for any a < b that returns true, b > a should also return true. Therefore, to be consistent with the expected inequality behaviors, you need to define both ThisType < ThatType and ThatType > ThisType. The asymmetric property, and the guidance for implementing operators symmetrically, means that you also have to define ThisType > ThatType and ThatType < ThisType. The transitive property says you also have to define ThisType > ThisType and ThisType < ThisType if you haven’t already. Finally, the guidance about implementing IComparable<T> says that both ThisType and ThatType should be IComparable<T> against each other (and themselves)—a task that can be accomplished only when ThisType and ThatType are in the same assembly.

Rather than implementing six different operators (and even more if <= is supported), two interfaces, and two methods, consider making use of a conversion operator (section 5.7.2) or a method or property that converts one type to another. For example, DateTimeOffset and DateTime can be compared via inequality:

Click here to view code image

DateTimeOffset a = GetDateTimeOffset();
DateTime b = GetDateTime();

// This compiles and behaves as expected
if (a < b) {
  ...
}

DateTimeOffset doesn’t define an operator < to compare against a DateTime, but instead has an implicit conversion operator to convert a DateTime into a DateTimeOffset and an operator < to compare two DateTimeOffset values:

Click here to view code image

public partial struct DateTimeOffset {
 public static implicit operator DateTimeOffset(DateTime dateTime) {...}

 public static operator <(DateTimeOffset left, DateTimeOffset right){...}
}

DateTimeOffset values can be compared to DateTime values (the other direction) by using the DateTimeOffset.UtcDateTime property.

Click here to view code image

public partial struct DateTimeOffset {
 public DateTime UtcDateTime { get { ... } }
}

5.8.1 Choosing Between Enum and Boolean Parameters

A framework designer often must decide when to use enums and when to use Booleans for parameters. In general, you should favor using enums if doing so improves the readability of the client code, especially in commonly used APIs. If using enums would add unneeded complexity and actually hurt readability, or if the API is very rarely used, use Booleans instead.

DO use enums if a member would otherwise have two or more Boolean parameters.

Enums are much more readable when it comes to books, documentation, source code reviews, and so on. For example, look at the following method call:

Click here to view code image

Stream stream = File.Open("foo.txt", true, false);

This call gives the reader no context within which to understand the meaning of true and false. The call would be much more usable if it were to use enums, as follows:

Click here to view code image

Stream stream = File.Open("foo.txt", CasingOptions.CaseSensitive,
FileMode.Open);

File.Open("foo.txt", true, false);

File.Open("foo.txt", caseSensitive: true, create: false);

DO NOT use Boolean parameters unless you are absolutely sure there will never be a need for more than two values.

Enums give you some room for future addition of values, but you should be aware of all the implications of adding values to enums, as described in section 4.8.2.

CONSIDER using Booleans for constructor parameters that are truly two-state values and are simply used to initialize Boolean properties.

5.8.2 Validating Arguments

Rigorous checks on arguments passed to members are a crucial element of modern reusable libraries. Although argument checks might have a slight impact on performance, end users are in general willing to pay the price for the benefit of better error reporting, which becomes possible if arguments are validated as high on the call stack as possible.

DO validate arguments passed to public, protected, or explicitly implemented members. Throw System.ArgumentException, or one of its subclasses, if the validation fails.

Click here to view code image

public class StringCollection : IList {
   int IList.Add(object item){
       string str = item as string;
       if(str==null) throw new ArgumentNullException(...);
       return Add(str);
   }
}

Note that the actual validation does not necessarily have to happen in the public or protected member itself. It could happen at a lower level in some private or internal routine. The main point is that the entire surface area that is exposed to the end users checks the arguments.

DO throw ArgumentNullException if a null argument is passed and the member does not support null arguments.

DO validate enum parameters.

Do not assume enum arguments will be in the range defined by the enum. The CLR allows casting any integer value into an enum value even if the value is not defined in the enum.

Click here to view code image

public void PickColor(Color color) {
  if(color > Color.Black || color < Color.White){
    throw new ArgumentOutOfRangeException(...);
  }
...
}

DO NOT use Enum.IsDefined for enum range checks.

public void PickColor(Color color) {
  // the following check is incorrect!
  if (!Enum.IsDefined (typeof(Color), color) {
      throw new InvalidEnumArgumentException(...);
  }
  // issue: never pass a negative color value
  NativeMethods.SetImageColor (color, byte[] image);
}
// call site
Foo.PickColor ((Color) -1); //throws InvalidEnumArgumentException

public enum Color {
  Red = 1,
  Green = 2,
  Blue = 3,
  Ultraviolet = -1, //new value added this version
}

//causes a buffer overrun in NativeMethods.SetImageColor() Foo.
PickColor ((Color) -1);

DO be aware that mutable arguments might have changed after they were validated.

If the member is security-sensitive, you are encouraged to make a copy and then validate and process the argument.

5.8.3 Parameter Passing

From the perspective of a framework designer, there are four main groups of parameters: by-value parameters, ref parameters, in (ref readonly) parameters, and out parameters.

When an argument is passed through a by-value parameter, the member receives a copy of the actual argument passed in. If the argument is a value type, a copy of the argument is put on the stack. If the argument is a reference type, a copy of the reference is put on the stack. Most popular CLR languages, such as C#, VB.NET, and C++, default to passing parameters by value.

Click here to view code image

public void Add (object value) {...}

When an argument is passed through a ref parameter, the member receives a reference to the actual argument passed in. If the argument is a value type, a reference to the argument is put on the stack. If the argument is a reference type, a reference to the reference is put on the stack. Ref parameters can be used to allow the member to modify arguments passed by the caller.

Click here to view code image

public static void Swap(ref object obj1, ref object obj2){
  object temp = obj1;
  obj1 = obj2;
  obj2 = temp;
}

In parameters are also called ref readonly parameters, and are similar to “normal” ref parameters. The most significant difference from ref parameters is that the receiving method cannot assign a replacement value through the parameter. For reference types, there is no functional difference between the default pass-by-reference and using the in parameter modifier—but using in makes all member accesses slower. For value types, a method cannot assign fields of an in parameter, and the compiler will make defensive copies of the parameter before invoking methods or properties—unless the type, method, or property accessor was declared with the readonly modifier (section 4.7). These defensive copies ensure that the called method cannot directly or indirectly modify the caller’s value.

Out parameters are similar to ref parameters, with some small differences. Such a parameter is initially considered unassigned and cannot be read in the member body before it is assigned some value. Also, the parameter has to be assigned some value before the member returns. For example, the following example will not compile and generates the compiler error “Use of unassigned out parameter ‘uri.’”

Click here to view code image

public class Uri {
  public bool TryParse(string uriString, out Uri uri){
    Trace.WriteLine(uri);
    ...
  }
}

AVOID using out or ref parameters except when implementing patterns that require them, such as the Try pattern (section 7.5.2).

Using out or ref parameters requires experience with pointers, understanding how value types and reference types differ, and handling methods with multiple return values. Also, the difference between out and ref parameters is not widely understood. Framework architects designing for a general audience should not expect users to master the challenge of working with out or ref parameters.

DO NOT pass reference types by reference (ref or in).

There are some limited exceptions to the rule, such as when a method can be used to swap references. There is no reason to pass a reference type with the in modifier (ref readonly semantics).

Click here to view code image

public static class Reference {
  public void Swap<T>(ref T obj1, ref T obj2){
    T temp = obj1;
    obj1 = obj2;
    obj2 = temp;
  }
}

DO NOT pass value types by read-only reference (in).

The main benefit of passing a value type by read-only reference is to reduce the cost of copying the value when the type is large. Since the guidance for value types is that they should be small (section 4.2), the performance benefit is slight. Conversely, if your method reads a property or invokes a method—without the appropriate readonly modifier—on an in parameter, you end up paying the cost silently. Once the compiler has made two defensive copies (or one copy if the type is small), your API now pays a performance penalty for the modifier, rather than receiving a performance boost.

This performance penalty risk, combined with some CLR languages having unpleasant syntax for passing by reference, means you should rarely, if ever, use the in modifier in public or protected methods.

5.8.4 Members with Variable Number of Parameters

Members that can take a variable number of arguments are expressed by providing an array parameter. For example, String provides the following method:

Click here to view code image

public class String {
  public static string Format(string format, object[] parameters);
}

A user can then call the String.Format method, as follows:

Click here to view code image

String.Format("File {0} not found in {1}",
 new object[]{filename,directory});

Adding the C# params keyword to an array parameter changes the parameter to a so-called params array parameter and provides a shortcut to creating a temporary array.

Click here to view code image

public class String {
   public static string Format(string format, params object[] parameters);
}

Doing this allows the user to call the method by passing the array elements directly in the argument list.

Click here to view code image

String.Format("File {0} not found in {1}",filename,directory);

Note that the params keyword can be added only to the last parameter in the parameter list.

CONSIDER adding the params keyword to array parameters if you expect the end users to pass arrays with a small number of elements.

If lots of elements will likely be passed in common scenarios, users will probably not pass these elements inline anyway, so the params keyword is not necessary.

AVOID using params arrays if the caller would almost always have the input already in an array.

For example, members with byte array parameters would almost never be called by passing individual bytes. For this reason, byte array parameters in .NET do not use the params keyword.

DO NOT use params arrays if the array is modified by the member taking the params array parameter.

Because many compilers turn the arguments to the member into a temporary array at the call site, the array might be a temporary object, and therefore any modifications to the array will be lost.

CONSIDER using the params keyword in a simple overload, even if a more complex overload could not use it.

Ask yourself if users would value having the params array in one overload, even if it wasn’t in all overloads. Consider the following overloaded method:

Click here to view code image

public class Graphics {
  FillPolygon(Brush brush, params Point[] points) { ... }
  FillPolygon(Brush brush, Point[] points, FillMode fillMode) {
    ...
  }
}

The array parameter of the second overload is not the last parameter in the parameter list, so it cannot use the params keyword. This does not mean that the keyword should not be used in the first overload, where it is the last parameter. If the first overload is used often, users will appreciate the addition.

DO try to order parameters to make it possible to use the params keyword.

Consider the following overloads on PropertyDescriptorCollection:

Click here to view code image

Sort()
Sort(IComparer comparer)
Sort(string[] names, IComparer comparer)
Sort(params string[] names)

Because of the order of parameters on the third overload, the opportunity to use the params keyword has been lost. The parameters could be reordered to allow for this keyword in both overloads.

Click here to view code image

Sort()
Sort(IComparer comparer)
Sort(IComparer comparer, params string[] names)
Sort(params string[] names)

CONSIDER providing special overloads and code paths for calls with a small number of arguments in extremely performance-sensitive APIs.

This makes it possible to avoid creating array objects when the API is called with a small number of arguments. Name the parameters by taking a singular form of the array parameter and adding a numeric suffix.

Click here to view code image

void Format (string formatString, object arg1)
  void Format (string formatString, object arg1, object arg2)
...
  void Format (string formatString, params object[] args)

You should do this only if you are going to treat the entire code path as a special case, not just create an array and call the more general method.

DO be aware that null could be passed as a params array argument.

You should validate that the array is not null before processing it.

Click here to view code image

static void Main() {
  Sum(1, 2, 3, 4, 5); //result == 15
  Sum(null);
}
static int Sum(params int[] values) {
  if(values==null) throw ArgumentNullException(...);
  int sum = ʘ;
  foreach (int value in values) {
    sum += value;
  }
  return sum;
}

DO NOT use the varargs methods, otherwise known as the ellipsis.

Some CLR languages, such as C++, support an alternative convention for passing variable parameter lists called varargs methods. This convention should not be used in frameworks, because it is not CLS-compliant.

5.8.5 Pointer Parameters

In general, pointers should not appear in the public surface area of a well-designed managed code framework. Most of the time, pointers should be encapsulated. However, pointers are sometimes required for interoperability reasons, and using pointers in such cases is appropriate.

The Span<T> and ReadOnlySpan<T> types unify native memory and managed arrays, and can be pinned to a pointer via the fixed keyword in C#. Using spans instead of pointers is preferred, when possible. For more information on spans, see section 9.12.

DO provide an alternative for any member that takes a pointer argument, because pointers are not CLS-compliant.

Click here to view code image

[CLSCompliant(false)]
public unsafe int GetBytes(char* chars, int charCount,
 byte* bytes, int byteCount);
public int GetBytes(char[] chars, int charIndex, int charCount,
 byte[] bytes, int byteIndex, int byteCount)

// Consider Span<T> / ReadOnlySpan<T> instead of
// (or in addition to) methods that take pointers
public int GetBytes(ReadOnlySpan<char> source, Span<byte> destination);

AVOID doing expensive argument checking for pointer arguments.

In general, argument checking is well worth the cost, but for APIs that are performance-critical enough to require using pointers, the overhead is often not worth it.

DO follow common pointer-related conventions when designing members with pointers.

For example, there is no need to pass the start index, because simple pointer arithmetic can be used to accomplish the same result.

Click here to view code image

//Bad practice
public unsafe int GetBytes(char* chars, int charIndex, int charCount,
 byte* bytes, int byteIndex, int byteCount)

//Better practice
public unsafe int GetBytes(char* chars, int charCount,
 byte* bytes, int byteCount)

//Example call site
GetBytes(chars + charIndex, charCount, bytes + byteIndex, byteCount);