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 xxv About the Authors xxvii 1 Introduction 1 1.1 Qualities of a Well-Designed Framework 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 S u m m a r y 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 N a m i n g Conventions 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 3.4 3.5 N a m e s of Assemblies a n d DLLs 48 N a m e s of Namespaces 49 3.4.I Namespaces and Type Name Conflicts 51 N a m e s of Classes, Structs, a n d 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 N a m e s 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 41

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 4.3 4.4 4.5 4.6

Choosing Between Class and Struct 74 Choosing Between Class and Interface 77 Abstract Class Design 83 Static Class Design 85 Interface Design 86

4.7 4.8

Struct Design 89 E n u m Design 91 4.8.1 Designing Flag Enums 97 4.8.2 Adding Values to Enums 100 N e s t e d Types 101

4.9

4.10 Summary 104

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 5.4 5.5 5.6 Constructor Design 125 5.3.1 Type Constructor Guidelines 131 Event Design 132 5.4.1 Custom Event Handler Design 138 Field Design 139 O p e r a t o r O v e r l o a d s 141 5.6.1 Overloading Operator == 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 146

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 7.2 Exception Throwing 183 Choosing the Right Type of Exception to Throw 7.2.1 Error Message Design 189 7.2.2 Exception Handling 7.2.3 Wrapping Exceptions 7.3 191 195 197 197 189

Using Standard Exception Types 7.3.2 ApplicationException 197

7.3.1 Exception and SystemException

7.3.3 InvalidOperationException 198 7 3 A ArgumentException, ArgumentNullException, and .. ArgumentOutOfRangeException 198 7.3.5 NullReferenceException, 7.3.6 StackOverflowException IndexOutOfRangeException, 200 and AccessViolationException 199 7.3.7 OutOfMemoryException 200 7.3.8 ComException, SEHException, and other CLR Exceptions 201 7.3.9 ExecutionEngineException 7.4 7.5 Exceptions and Performance 203 7.5.1 Tester-Doer Pattern 203 7.5.2 Try-Parse Pattern 204 201 Designing Custom Exceptions 202

7.6 Summary 205 8 Usage Guidelines 207

8.1 8.2 8.3 Arrays 207 Attributes 209 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 8.5 8.6 I C l o n e a b l e 221 IComparable<T> and I E q u a t a b l e < T > IDisposable 223 224 225 222

8.7 Object 224 8.7.1 Object.Equals 8.7.2 Object.GetHashCode 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 9.3 The Async Pattern 243 9.2.1 Async Pattern Basic Implementation Example 247 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