Chapter 2 of. NET Design Specifications: member design and. net Design Specifications

Chapter 2 of. NET Design Specifications: member design and. net Design Specifications
. NET Design Specifications Chapter 1: member design 5th General Design Specifications

Use descriptive parameter names as much as possible to describe the default values used in short overloading.

Avoid arbitrarily changing the parameter name in the overload. If one of the two overload parameters represents the same input, the parameter name should be the same.

Avoid inconsistent Parameter order of the reload members. In all overload operations, parameters with the same name should appear at the same location.

You must define the longest overload member as the unique Virtual Member in the overload member.

Do not use the ref or out modifier to reload members.

Do not define such overload: parameters at the same position have similar types but have different semantics.

You must allow the optional parameter to be set to null when passing the parameter.

Reload members is preferred, rather than defining members with default parameters.

Explicitly implement interface members.

Avoid explicitly implementing interface members-if there is no strong reason.

Explicitly implement the interface member-if you want the interface member to be called only through this interface.

Simulate Variants by explicitly implementing interface members.

Consider explicitly implementing interface members when you need to hide a member and add another equivalent Member with a more appropriate name.

Do not regard the display and implementation of interface members as security barriers.

Provide protected virtual members with the same functions for explicitly implemented interface members-if you want a derived class to customize the function.

Consider using attributes-if this member represents a logical attribute of the type.

Use attributes instead of methods-if the attribute value is stored in the process memory, the attribute is provided only to access the value.

Use methods instead of attributes in the following cases:

This operation is several orders of magnitude slower than field access;

This operation is a conversion operation, such as the object. ToString () method;

This operation returns different results for each call, even if the input parameters remain unchanged. For example, the Guid. NewGuid method returns different values each time;

This operation has serious and obvious side effects;

This operation returns a copy of the internal status (this does not include copies of value type objects returned on the stack );

This operation returns an array.

 

5.2 attribute Design

Create a read-only property-if the caller does not change the value of the property.

Do not provide write-only attributes, or make setter more accessible than getter.

Provide reasonable default values for all attributes to ensure that the default values do not cause security vulnerabilities or inefficient code.

You must allow users to set attribute values in any order, even if this may make the object invalid for a short time.

To retain the original property value, if the property setter throws an exception.

Avoid throwing an exception in the getter of the property.

You can use the indexer to access the data stored in a non-array.

Consider providing an indexer For the types that represent the element set.

Avoid using the index attribute with more than one parameter.

Avoid using types other than System. Int32, System. Int64, System. String, System. Object, enumeration, or generic parameters as index parameters.

To use the Item name for index properties, unless there are obviously better names (such as the Chars attribute of System. String ).

Do not provide semantic equivalent indexers and methods at the same time.

Do not provide indexers with different names in a type.

Do not use non-default index properties.

Consider a notification event that triggers a property change when the attribute value of a high-level API is modified.

A notification event is triggered when the attribute value is modified.

　　

5.3 Design of Constructor

Consider providing simple constructor, preferably the default constructor.

Consider using a static factory method to replace the constructor. If the semantics of the operation to be executed cannot directly correspond to the constructor of the new instance, or follow the constructor design specifications, it may be unreasonable.

You need to use the parameter list of the constructor as a shortcut to set the main attributes.

Use the same name to name the parameters and properties of the constructor.-If you define this constructor parameter, set the corresponding properties.

Do the least work in the constructor.

When appropriate, an exception should be thrown from the instance constructor.

Explicitly declare the common default constructor in the class-if such constructor is required.

Avoid explicitly defining the default constructor in the structure.

Avoid calling virtual members within the object constructor.

The static constructor should be declared as private.

Do not throw an exception from the static constructor.

Consider initializing static fields in the form of internal constructor instead of explicitly defining static constructor, because the runtime can optimize the performance of types that do not display and define static constructor.

 

5.4 event Design

Use the term "raise" in an event instead of "fire" or "trigger ".

Use System. EventHandler <T> to define the event processing function, instead of manually creating a new delegate to define the event processing function.

Consider using the EventArgs subclass as the event parameter, unless you are sure that the event does not need to pass any data to the event processing method, you can directly use EeventArgs in this case.

Use protected Virtual Methods to trigger events. This applies only to non-static events in non-sealed categories and not to structures, sealed categories, and static events.

To include a parameter in the protected method that triggers an event, the parameter type is event parameter class, and the parameter name should be e.

Do not pass null as the sender parameter when a non-static event is triggered.

Null must be passed in as the sender parameter when a static event is triggered.

Do not pass null as a data parameter when an event is triggered.

Consider triggering events that can be canceled by end users. This applies to pre-events.

Define the return type of the event processing function as void.

Use an object as the type of the first parameter of the event processing function and name it sender.

Use System. EventArgs or its subclass as the type of the second parameter of the event processing function, and name it e.

Do not use more than two parameters in the event processing function.

　　

5.5 Field Design

Do not provide public or protected instance fields.

Use constant fields to represent constants that will never change.

Use a public static read-only field to define a pre-defined object instance.

Do not assign a variable type instance to a read-only field.

　　

5.6 Extension Method

Avoid rashly defining extension methods, especially for other types.

Consider using the Extension Method in the following scenarios.

Provides auxiliary methods for all implementations of an interface, and these functions can be expressed through core interfaces.

If you add an instance method to introduce dependencies of other types, and the dependency will damage the dependency management rules, you should use the extension method.

Avoid defining extension methods for System. Object.

Do not place extension methods and types in the same namespace unless you want to add methods to interfaces or manage dependencies.

Avoid using the same signature when defining two extension methods, even if they are in different namespaces.

Consider placing the extension method and the extended type in the same namespace-if the extended type is an interface, the extension method is designed to be used in most cases or even all cases.

Do not place extension methods that implement a feature in a namespace that is usually associated with other features. On the contrary, the corresponding extension method should be put in the namespace of the feature.

Avoid using too broad names (for example, "Extensions") to name namespaces dedicated to extension methods, and use more descriptive names (for example, "Routing ").

　　

5.7 operator overload

Avoid defining Operator Overloading unless this type is a basic (built-in) type.

Consider defining Operator Overloading in a type that makes people feel like a basic type.

Operator Overloading is defined for the structure that represents a value (such as System. Decimal.

Do not be clever when defining Operator overloading.

Do not provide Operator Overloading unless at least one operand is the type that defines the operator overloading.

Operators must be reloaded in symmetric mode.

Consider providing corresponding methods for each overloaded operator and naming it with a name that is easy to understand.

Do not provide the type conversion operator-if there is no clear user requirement.

Do not go beyond the field of the type when defining the type conversion operator.

Do not provide implicit type conversion operators-if such type conversion is possible, precision may be lost.

Do not throw an exception from the implicit forced type conversion operator.

System. InvalidCastException to be thrown-if you call a forced type conversion operator, precision is lost, and the operator promises not to lose precision.

 

5.8 Parameter Design

Use the type closest to the base class in the class hierarchy as the parameter type, and ensure that the type can provide the functions required by members.

Do not use reserved parameters.

Do not use pointers, pointer arrays, and multi-dimensional arrays as parameters of public methods.

All output parameters should be placed behind all parameters passed in value mode and reference mode (excluding parameter arrays ), this is required even if the Parameter order is inconsistent between the overloaded members.

The parameter names must be consistent when overwriting members or implementing interface members.

Use enumeration-if you do not do this, there will be two or more Boolean types in the parameter.

Do not use a Boolean parameter, unless two or more values are definitely not required.

In the constructor, only two state parameters and the parameters used to initialize the Boolean attribute must be of the boolean type.

To verify the parameters passed to common, protected, or explicitly implemented members. If the verification fails, System. ArgumentException or its subclass should be thrown.

ArgumentNullExcepytion to be thrown-if the input is null, this member does not support null.

You need to verify the enumerated parameters.

Do not use Enum. IsDefined to check the enumerated range.

It should be clear that the passed variable parameters may change after verification.

Avoid using output or reference parameters.

Do not pass the reference type as a reference.

Consider adding the params keyword to the array parameter-if you are expected to pass in a small number of array elements.

Avoid using params array parameters-if the array elements to be passed in by the caller are already in an array in most cases.

Do not use params array parameters-if you want to modify the array in the member.

Consider using the params keyword in simple overloading, although the params keyword cannot be used in more complex overloading.

You must sort the parameters reasonably to use the params keyword.

In order to provide special overloading and implementation for calls with a small number of parameters in APIs with high performance requirements.

Note that the input params array parameter may be null.

Do not use the varargs method, or ellipsis.

To provide a substitute member for any member with the pointer as the parameter, this is because the pointer does not comply with the CLS specification.

Avoid high-availability checks on Pointer parameters.

You must follow the common conventions related to pointers when designing members that use pointers.