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 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  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  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

Other Resources

Type Design Guidelines
Design Guidelines for Developing Class Libraries