Design Guidelines For Class Library

Design Guidelines for Class Library Developers
These guidelines are intended to help class library designers understand the trade-offs between different solutions. There might be situations where good library design requires that you violate these design guidelines. Such cases should be rare, and it is important that you provide a solid justification for your decision. The section providesnaming and usage guidelines for types in the .NET Framework as well as guidelines for implementing common design patterns.

Contents


Guidelines for Names 6
Capitalization Styles 7
Abbreviations 8
Word Choice 8
Names of Classes, Structs, and Interfaces 8
Classes and structs 8
Names of Generic Type Parameters 9
Interface Naming Guidelines 9
Enumeration Type Naming Guidelines 9Names of Type Members 10
Method Naming Guidelines 10
Property Naming Guidelines 10
Read-Only and Write-Only Properties 10
Indexed Property Usage 10
Field Usage Guidelines 11
Static Field Naming Guidelines 11
Namespaces Naming Guidelines 11
Event Naming Guidelines 12
Attribute Naming Guidelines 12
Parameter Naming Guidelines 13
Resources Naming Guidelines 14
RegionsGuidelines 14
Comments 15
Member Design Guidelines 16
Member Overloading 16
Implementing Interface Members Explicitly 17
Choosing Between Properties and Methods 17
Property Design 18
Constructor Design 18
Event Design 19
Field Design 19
Operator Overloads 20
Conversion Operators 20
Parameter Design 21
Choosing between Enumerations and Boolean Parameters 21
Members with avariable number of Parameters 22
Pointer Parameters 23
Passing Parameters 23
Validating Arguments 23
Type Design Guidelines 25
Types and Namespaces 25
Choosing between Classes and Structures 25
Choosing between Abstract Classes and Interfaces 26
Abstract Class Design 26
Static Class Design 27
Interface Design 27
Structure Design 28
Enumeration Design 29
Nested Types 29Designing for Extensibility 31
Unsealed Classes 31
Protected Members 31
Events and Callbacks 31
Virtual Members 32
Abstract Types and Interfaces 32
Base Classes for Implementing Abstractions 33
Limiting Extensibility by Sealing Classes 33
Design Guidelines for Exceptions 35
Exception Throwing 35
Choosing the Right Type of Exception to Throw 36
Wrapping Exceptions 36
ErrorMessage Design 36
Exception Handling 37
Catching and Throwing Standard Exception Types 37
Exception and SystemException 37
ApplicationException 37
InvalidOperationException 38
ArgumentException, ArgumentNullException, and ArgumentOutOfRangeException 38
StackOverflowException 38
OutOfMemoryException 38
ComException and SEHException 38
ExecutionEngineException 38
Designing CustomExceptions 39
Exceptions and Performance 40
Usage Guidelines 41
Array Usage Guidelines 41
Arrays vs. Collections 41
Array Usage 41
Properties that Return Arrays 42
Fields that Return Arrays 42
Using Indexed Properties in Collections 42
Returning Empty Arrays 42
Attribute Usage Guidelines 43
Guidelines for Implementing Equals and the Equality Operator (==) 44
Implementing theEquality Operator (==) on Value Types 44
Implementing the Equality Operator (==) on Reference Types 44
Dessign Patterns 45
Implementing Finalize and Dispose to Clean Up Unmanaged Resources 45
Customizing a Dispose Method Name 46
Finalize 46
Dispose 47
Time-Out Usage 48

Guidelines for Names
A consistent naming pattern is one of the most important elements of predictability anddiscoverability in a managed class library. Widespread use and understanding of these naming guidelines should eliminate many of the most common user questions. This topic provides naming guidelines for the .NET Framework types. For each type, you should also take note of some general rules with respect to capitalization styles, case sensitivity and word choice.

Capitalization Styles
Use the...