Framework Design Guidelines Conventions, Idioms, and Patterns for Reusable.NET Libraries Krzysztof Cwalina Brad Abrams Addison-Wesley Upper Saddle River, NJ Boston Indianapolis San Francisco New York Toronto Montreal London Munich Paris Madrid Capetown Sydney Tokyo Singapore Mexico City
Contents Figures xiii Tables xv Foreword xvii Preface xix Acknowledgments About the Authors xxv xxvii 1 Introduction 1 1.1 Qualities of a Well-Designed Framework 3 1.1.1 Well-Designed Frameworks Are Simple 3 1.1.2 Well-Designed Frameworks Are Expensive to Design 3 1.1.3 Well-Designed Frameworks Are Full of Trade-Offs 4 1.1. A Well-Designed Frameworks Borrow from the Past 5 1.1.5 Well-Designed Frameworks Are Designed to Evolve 5 1.1.6 Well-Designed Frameworks Are Integrated 5 1.1.7 Well-Designed Frameworks Are Consistent 6 2 Framework Design Fundamentals 7 2.1 Progressive Frameworks 9 2.2 Fundamental Principles of Framework Design 12 2.2.1 The Principle of Scenario-Driven Design 13 2.2.2 The Principle of Low Barrier to Entry 19 2.2.3 The Principle of Self-Documenting Object Models 23 2.2 A The Principle of Layered Architecture 29 2.3 Summary 31 VII
3 Naming Guidelines 33 3.1 Capitalization Conventions 34 3.1.1 Capitalization Rules for Identifiers 34 3.1.2 Capitalizing Acronyms 36 3.1.3 Capitalizing Compound Words and Common Terms 39 3.1.4 Case Sensitivity 41 3.2 General Naming Conventions 41 3.2.1 Word Choice 42 3.2.2 Using Abbreviations and Acronyms 43 3.2.3 Avoiding Language-Specific Names 44 3.2.4 Naming New Versions of Existing APIs 46 3.3 Names of Assemblies and DLLs 48 3.4 Names of Namespaces 49 3.4.I Namespaces and Type Name Conflicts 51 3.5 Names of Classes, Structs, and Interfaces 54 3.5.1 Names of Generic Type Parameters 56 3.5.2 Names of Common Types 57 3.5.3 Naming Enumerations 59 3.6 Names of Type Members 60 3.6.1 Names of Methods 60 3.6.2 Names of Properties 61 3.6.3 Names of Events 63 3.6.4 Naming Fields 64 3.7 Naming Parameters 64 3.8 Naming Resources 65 3.9 Summary 66 4 Type Design Guidelines 67 4.1 Types and Namespaces 69 4.1.1 Standard Subnamespace Names 73 4.2 Choosing Between Class and Struct 74 4.3 Choosing Between Class and Interface 77 4.4 Abstract Class Design 83 4.5 Static Class Design 85 4.6 Interface Design 86
4.7 Struct Design 89 4.8 Enum Design 91 4.8.1 Designing Flag Enums 97 4.8.2 Adding Values to Enums 100 4.9 Nested Types 101 4.10 Summary 104 5 Member Design 105 5.1 General Member Design Guidelines 105 5.1.1 Member Overloading 105 5.1.2 Implementing Interface Members Explicitly 111 5.1.3 Choosing Between Properties and Methods 115 5.2 Property Design 120 5.2.1 Indexed Property Design 122 5.2.2 Property Change Notification Events 124 5.3 Constructor Design 125 5.3.1 Type Constructor Guidelines 131 5.4 Event Design 132 5.4.1 Custom Event Handler Design 138 5.5 Field Design 139 5.6 Operator Overloads 141 5.6.1 Overloading Operator == 146 5.6.2 Conversion Operators 146 5.7 Parameter Design 148 5.7.1 Choosing Between Enum and Boolean Parameters 150 5.7.2 Validating Arguments 152 5.7.3 Parameter Passing 155 5.7.4 Members with Variable Number of Parameters 157 5.7.5 Pointer Parameters 161 5.8 Summary 162 6 Designing for Extensibility 163 6.1 Extensibility Mechanisms 163 6.1.1 Unsealed Classes 164 6.1.2 Protected Members 165 6.1.3 Events and Callbacks 166
6.1.4 Virtual Members 168 6.1.5 Abstractions (Abstract Types and Interfaces) 170 6.2 Base Classes 172 6.3 Sealing 174 6.4 Summary 177 7 Exceptions 179 7.1 Exception Throwing 183 7.2 Choosing the Right Type of Exception to Throw 189 7.2.1 Error Message Design 189 7.2.2 Exception Handling 191 7.2.3 Wrapping Exceptions 195 7.3 Using Standard Exception Types 197 7.3.1 Exception and SystemException 197 7.3.2 ApplicationException 197 7.3.3 InvalidOperationException 198 7.3.A ArgumentException, ArgumentNullException, and ArgumentOutOfRangeException 198 7.3.5 NullReferenceException, IndexOutOfRangeException, and AccessViolationException 199 7.3.6 StackOverflowException 200 7.3.7 OutOfMemoryException 200 7.3.8 ComException, SEHException, and other CLR Exceptions 201 7.3.9 ExecutionEngineException 201 7.4 Designing Custom Exceptions 202 7.5 Exceptions and Performance 203 7.5.1 Tester-Doer Pattern 203 7.5.2 Try-Parse Pattern 204 7.6 Summary 205 8 Usage Guidelines 207 8.1 Arrays 207 8.2 Attributes 209 8.3 Collections 211 8.3.1 Collection Parameters 213 8.3.2 Collection Properties and Return Values 214
8.3.3 Choosing Between Arrays and Collections 218 8.3.4 Implementing Custom Collections 219 8.4 ICloneable 221 8.5 IComparable<T> and IEquatable<T> 222 8.6 IDisposable 223 8.7 Object 224 8.7.1 Object.Equals 224 8.7.2 Object.GetHashCode 225 8.7.3 Object. ToString 227 8.8 Uri 228 8.8.1 System. Uri Implementation Guidelines 229 8.9 System.Xml Usage 230 8.10 Equality Operators 231 8.10.1 Equality Operators on Value Types 232 8.10.2 Equality Operators on Reference Types 232 9 Common Design Patterns 235 9.1 Aggregate Components 235 9.1.1 Component-Oriented Design 237 9.1.2 Factored Types 240 9.13 Aggregate Component Guidelines 240 9.2 The Async Pattern 243 9.2.1 Async Pattern Basic Implementation Example 247 9.3 Dispose Pattern 248 9.3.1 Basic Dispose Pattern 251 9.3.2 Finalizable Types 256 9.4 Factories 260 9.5 Optional Feature Pattern 264 9.6 Template Method 267 9.7 Timeouts 269 9.8 And in the End... 271 A C# Coding Style Conventions 273 A.I General Style Conventions 274
A. 1.1 Brace Usage 274 A.I.2 Space Usage 275 A. 1.3 Indent Usage 276 A. 2 Naming Conventions 277 A3 Comments 277 A.4 File Organization 278 B Using FxCop to Enforce the Design Guidelines 281 B.I WhatlsFxCop? 281 B.2 The Evolution of FxCop 282 B.3 How Does It Work? 283 B.4 FxCop Guideline Coverage 284 B.4.1 FxCop Rules for the Naming Guidelines 284 B.4.2 FxCop Rules for the Type Design Guidelines 293 B.4.3 FxCop Rules for Member Design 296 B.4.4 FxCop Rules for Designing for Extensibility 302 B.4.5 FxCop Rules for Exceptions 303 B.4.6 FxCop Rules for Usage Guidelines 305 B.4.7 FxCop Rules for Design Patterns 309 C Sample API Specification 311 Glossary 319 Suggested Reading List 323 Index 327