Structure Design
Structures are value types. They are allocated on the stack or inline and are deallocated when they go out of scope. In general, value types are cheaper to allocate and deallocate; however, if they are used in scenarios that require a significant amount of boxing and unboxing, they perform poorly as compared to reference types. For more information, see Boxing and Unboxing (C# Programming Guide).
For additional information about value types and reference types, see the Common Type System Overview.
Do not provide a default constructor for a structure.
If a structure defines a default constructor, when arrays of the structure are created, the common language runtime automatically executes the default constructor on each array element.
Some compilers, such as the C# compiler, do not allow structures to have default constructors.
Do implement System.IEquatable`1 on value types.
IEquatable<T> is preferred over Equals to determine whether two value types are equal. By using the interface, the caller avoids the negative performance impact of boxing and managed reflection.
Do ensure that a state where all instance data is set to zero, false, or null (as appropriate) is valid.
By following this guideline, your newly constructed value type instances are not left in an unusable state. For example, the following structure is incorrectly designed. The parameterized constructor is meant to ensure a valid state, but the constructor is not executed when an array of the structure is created. This means that the instance field label gets initialized to null (Nothing in Visual Basic), which is not valid for this structure's implementation of ToString.
Public Structure BadStructure
Private label As String
Private width As Integer
Private length As Integer
Public Sub New(ByVal labelValue As String, ByVal widthValue As Integer, ByVal lengthValue As Integer)
If ((labelValue = Nothing) _
OrElse (labelValue.Length = 0)) Then
Throw New ArgumentNullException("label")
End If
label = labelValue
width = widthValue
length = lengthValue
End Sub
Public Overrides Function ToString() As String
' Accessing label.Length throws a NullReferenceException
' when label is null.
Return String.Format("Label length: {0} Label: {1} Width: {2} Length: {3}", label.Length, label, width, length)
End Function
End Structure
public struct BadStructure
{
string label;
int width;
int length;
public BadStructure (string labelValue, int widthValue, int lengthValue)
{
if (labelValue == null || labelValue.Length ==0)
{
throw new ArgumentNullException("label");
}
label = labelValue;
width = widthValue;
length = lengthValue;
}
public override string ToString()
{
// Accessing label.Length throws a NullReferenceException
// when label is null.
return String.Format("Label length: {0} Label: {1} Width: {2} Length: {3}",
label.Length, label, width,length);
}
}
In the following code example, the design of GoodStructure makes no assumptions about the state of the label field. The ToString method is designed to handle a null label.
Public Structure GoodStructure
Private label As String
Private width As Integer
Private length As Integer
Public Sub New(ByVal labelValue As String, ByVal widthValue As Integer, ByVal lengthValue As Integer)
label = labelValue
width = widthValue
length = lengthValue
End Sub
Public Overrides Function ToString() As String
' Handle the case where label might be
' initialized to null;
Dim formattedLabel As String = label
Dim formattedLableLength As Integer
If (formattedLabel = Nothing) Then
formattedLabel = "<no label value specified>"
formattedLableLength = 0
Else
formattedLableLength = label.Length
End If
Return String.Format("Label Length: {0} Label: {1} Width: {2} Length: {3}", formattedLableLength, formattedLabel, width, length)
End Function
End Structure
public struct GoodStructure
{
string label;
int width;
int length;
public GoodStructure (string labelValue, int widthValue, int lengthValue)
{
label = labelValue;
width = widthValue;
length = lengthValue;
}
public override string ToString()
{
// Handle the case where label might be
// initialized to null;
string formattedLabel = label;
int formattedLableLength;
if (formattedLabel == null)
{
formattedLabel = "<no label value specified>";
formattedLableLength = 0;
} else
{
formattedLableLength = label.Length;
}
return String.Format("Label Length: {0} Label: {1} Width: {2} Length: {3}",
formattedLableLength, formattedLabel, width, length);
}
}
Do not explicitly extend System.ValueType.
Some compilers do not allow you to extend ValueType.
Portions Copyright 2005 Microsoft Corporation. All rights reserved.
Portions Copyright Addison-Wesley Corporation. All rights reserved.
For more information on design guidelines, see the "Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries" book by Krzysztof Cwalina and Brad Abrams, published by Addison-Wesley, 2005.
See Also
Concepts
Choosing Between Classes and Structures