". NET Design Specification" Chapter 5th: Member Design

The. NET design Specification, Chapter 5th: General specification for member Design 5.1 member design

Try to use descriptive parameter names to describe the default values that are used in shorter overloads.

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

Avoid making the parameter order of overloaded members inconsistent. In all overloads, the same name parameter should appear in the same position.

To define the longest overloaded member as the only virtual member in an overloaded member.

Do not overload members with ref or out modifiers.

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

To allow optional parameters to be set to NULL when parameters are passed.

Instead of defining a member with default parameters, you prefer to use member overloading.

Explicitly implement an interface member.

Avoid displaying the interface members-if there is no strong reason to do so.

Consider explicitly implementing an interface member-if you want an interface member to be called only through that interface.

Consider simulating variants by explicitly implementing an interface member.

Consider explicitly implementing an interface member when you need to hide a member and add an equivalent member that is more appropriate for another name.

Do not consider the display implementation of interface members as a security barrier.

To provide a protected virtual member with the same functionality for an explicitly implemented interface member-if you want the derived class to customize the feature.

Consider using a property-if the member represents a logical property of the type.

To use a property instead of a method-if the value of the property is stored in process memory, and the property is provided only to access the value.

To use a method instead of a property in the following situations:

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

The operation is a conversion operation, such as: object. ToString () method;

The operation returns a different result on each invocation, even if the passed parameter is not changed. For example: The Guid.NewGuid method returns a different value each time;

This operation has serious and obvious side effects;

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

The operation returns an array.

5.2 Design of attributes

To create a read-only property-if the caller should not change the value of the property.

Do not provide write-only properties, and do not make the setter more accessible than getter.

To provide a reasonable default value for all properties, you can ensure that the default value does not result in a security vulnerability or inefficient code.

To allow the user to set the value of the property in any order, even though this may cause the object to be in an invalid state for a short period of time.

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

Avoid throwing exceptions in the getter of a property.

Consider using indexers to give users access to data stored in arrays.

Consider providing an indexer for the type that represents the collection of elements.

Avoid using indexed properties that have more than one parameter.

Avoid using types other than System.Int32, System.Int64, System.String, System.Object, enumerations, or generic parameters as parameters for indexers.

The Item name is used for indexed properties unless there is a significantly better name (such as the Chars property of System.String).

Do not provide both semantically equivalent indexers and methods.

Do not provide indexers with different names in a type.

Do not use non-default indexed properties.

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

Consider triggering notification events when property values are modified by the outside world.

　　

5.3 Design of the structure function

Consider providing a simple constructor, preferably a default constructor.

Consider using a static factory method instead of a constructor-if it is not possible to have the semantics of the action you want to perform directly with the constructor of the new instance, or to follow the design specification of the constructor, it makes sense.

Consider the argument list of the constructor as a quick way to set the primary property.

The parameters and properties of the constructor are named with the same name-if the constructor parameter is defined to set the corresponding property.

To do the least work in the constructor.

To throw an exception from the instance constructor at the appropriate time.

To explicitly declare a public default constructor in a class-if such a constructor is required.

Avoid explicitly defining default constructors in structs.

Avoid calling virtual members inside the object's constructor.

To declare a static constructor as private.

Do not throw an exception from the static constructor.

Consider initializing static fields in an inline form, rather than explicitly defining static constructors, because the runtime can perform performance optimizations on types that do not display the definition of a static constructor.

5.4 Design of the event

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

Instead of manually creating a new delegate to define an event handler, you use system.eventhandler<t> to define the event handler function.

Consider using a subclass of EventArgs to do the arguments of the event, unless you are absolutely sure that the event does not need to pass any data to the event-handling method, in which case you can use Eeventargs directly.

The event is to be triggered with a protected virtual method. This applies only to non-static events in unsealed classes, not to structures, sealed classes, and static events.

To have a protected method that triggers an event with a parameter whose type is the event argument class, the name of the parameter should be E.

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

To pass NULL as the sender parameter when a static event is triggered.

Do not pass NULL as a data parameter when the event is triggered.

Consider triggering an event that can be canceled by the end user, which applies to the predecessor event.

The return type of the event handler function is defined as void.

Use object as the type of the first parameter of the event handler and name it sender.

Use System.EventArgs or its subclasses as the type of the second parameter of the event handler and name it E.

Do not use more than two arguments in an event handler.

　　

5.5 Design of the field

Do not provide public or protected instance fields.

Constant fields are used to represent constants that never change.

To define a predefined object instance with a public static read-only field.

Do not assign an instance of a mutable type to a read-only field.

　　

5.6 Extension methods

Avoid sloppy definition of extension methods, especially for other people's types.

Consider using an extension method in the following scenario.

Provides an associated helper method for all implementations of an interface, and these functions can be expressed through a core interface.

If you add an instance method that introduces dependencies on other types, and dependencies break management rules for dependencies, you should use extension methods.

Avoid defining extension methods for System.Object.

Do not put extension methods and extended types in the same namespace-except to add methods to the interface or to manage dependencies.

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

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

Do not put an extension method that implements an attribute in a namespace that is typically associated with other attributes. Instead, the attribute belongs to which namespace, and the corresponding extension method should be placed there.

Avoid using names that are too broad (such as "Extensions") to name namespaces that are specific to extension methods, using a more descriptive name (such as "Routing").

　　

5.7 Operator overloading

Avoid defining operator overloading unless the type feels like a basic (built-in) type.

Consider defining operator overloads in types that make people feel like they should be primitive types.

To define operator overloads for structures that represent numeric values, such as System.Decimal.

Do not be smart when defining operator overloading.

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

You want to overload the operator in a symmetric manner.

Consider providing a corresponding method for each overloaded operator and naming it with an easy-to-understand name.

Do not provide a type conversion operator-if there is no explicit user requirement.

Do not go beyond the realm of types when defining type conversion operators.

Do not provide an implicit type conversion operator-if such a type conversion might lose precision.

Do not throw an exception from an implicit coercion type conversion operator.

To throw System.InvalidCastException-if a call to a forced type conversion operator loses precision and the operator commits to not lose precision.

5.8 Design of parameters

Use the type closest to the base class in the class hierarchy as the type of the parameter, and ensure that the type provides the functionality required by the member.

Do not use reserved parameters.

Do not use pointers, pointer arrays, and multidimensional arrays as parameters to public methods.

To place all output parameters after all parameters that are passed by value and by reference (not including parameter arrays), even if this causes the parameter order to be inconsistent between overloaded members.

Keep parameter naming consistent when overriding members or implementing interface members.

To use enumerations-if you do not do this, it causes two or more two Boolean types in the argument.

Do not use Boolean parameters unless you absolutely definitely don't need more than two values.

Consider using a Boolean type in the constructor for parameters that do have only two states, and for parameters that initialize the Boolean property.

The parameters to pass to the members that are shared, protected, or explicitly implemented are validated. If the validation fails, then System.ArgumentException or its subclasses should be thrown.

To throw argumentnullexcepytion-if NULL is passed in and the member does not support NULL.

The enumeration parameter to validate.

Do not use enum.isdefined to check the scope of the enumeration.

It is clear to know that the incoming mutable parameters may change after validation.

Avoid using output parameters or reference parameters.

Do not pass reference types in a reference manner.

Consider adding the params keyword to the array parameter-if you expect the user to pass in a few array elements.

Avoid using params array parameters-if most of the time the caller is going to pass in an array element that is already in an array.

Do not use the params array parameter-if you want to modify a group in a member.

Consider using the params keyword in a simple overload, although a more complex overload cannot be used with the params keyword.

To sort the parameters reasonably, use the params keyword.

Consider providing special overloads and corresponding implementations for calls with a low number of parameters in an API that is highly performance-demanding.

Note that the params array parameter passed in May be null.

Do not use the VarArgs method, also called the ellipsis.

To provide a substitute member for any member that takes a pointer argument, because the pointer is not CLS-compliant.

Avoid high-overhead checks on pointer parameters.

To follow the common conventions associated with pointers when designing members that use pointers.

　　

". NET Design Specification" Chapter 5th: Member Design