Framework Design Guidelines

Transcription

1 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

2 Contents Figures xiii Tables xv Foreword xvii Preface xix Acknowledgments About the Authors xxv xxvii 1 Introduction Qualities of a Well-Designed Framework Well-Designed Frameworks Are Simple Well-Designed Frameworks Are Expensive to Design Well-Designed Frameworks Are Full of Trade-Offs A Well-Designed Frameworks Borrow from the Past Well-Designed Frameworks Are Designed to Evolve Well-Designed Frameworks Are Integrated Well-Designed Frameworks Are Consistent 6 2 Framework Design Fundamentals Progressive Frameworks Fundamental Principles of Framework Design The Principle of Scenario-Driven Design The Principle of Low Barrier to Entry The Principle of Self-Documenting Object Models A The Principle of Layered Architecture Summary 31 VII

3 3 Naming Guidelines Capitalization Conventions Capitalization Rules for Identifiers Capitalizing Acronyms Capitalizing Compound Words and Common Terms Case Sensitivity General Naming Conventions Word Choice Using Abbreviations and Acronyms Avoiding Language-Specific Names Naming New Versions of Existing APIs Names of Assemblies and DLLs Names of Namespaces I Namespaces and Type Name Conflicts Names of Classes, Structs, and Interfaces Names of Generic Type Parameters Names of Common Types Naming Enumerations Names of Type Members Names of Methods Names of Properties Names of Events Naming Fields Naming Parameters Naming Resources Summary 66 4 Type Design Guidelines Types and Namespaces Standard Subnamespace Names Choosing Between Class and Struct Choosing Between Class and Interface Abstract Class Design Static Class Design Interface Design 86

4 4.7 Struct Design Enum Design Designing Flag Enums Adding Values to Enums Nested Types Summary Member Design General Member Design Guidelines Member Overloading Implementing Interface Members Explicitly Choosing Between Properties and Methods Property Design Indexed Property Design Property Change Notification Events Constructor Design Type Constructor Guidelines Event Design Custom Event Handler Design Field Design Operator Overloads Overloading Operator == Conversion Operators Parameter Design Choosing Between Enum and Boolean Parameters Validating Arguments Parameter Passing Members with Variable Number of Parameters Pointer Parameters Summary Designing for Extensibility Extensibility Mechanisms Unsealed Classes Protected Members Events and Callbacks 166

5 6.1.4 Virtual Members Abstractions (Abstract Types and Interfaces) Base Classes Sealing Summary Exceptions Exception Throwing Choosing the Right Type of Exception to Throw Error Message Design Exception Handling Wrapping Exceptions Using Standard Exception Types Exception and SystemException ApplicationException InvalidOperationException A ArgumentException, ArgumentNullException, and ArgumentOutOfRangeException NullReferenceException, IndexOutOfRangeException, and AccessViolationException StackOverflowException OutOfMemoryException ComException, SEHException, and other CLR Exceptions ExecutionEngineException Designing Custom Exceptions Exceptions and Performance Tester-Doer Pattern Try-Parse Pattern Summary Usage Guidelines Arrays Attributes Collections Collection Parameters Collection Properties and Return Values 214

6 8.3.3 Choosing Between Arrays and Collections Implementing Custom Collections ICloneable IComparable<T> and IEquatable<T> IDisposable Object Object.Equals Object.GetHashCode Object. ToString Uri System. Uri Implementation Guidelines System.Xml Usage Equality Operators Equality Operators on Value Types Equality Operators on Reference Types Common Design Patterns Aggregate Components Component-Oriented Design Factored Types Aggregate Component Guidelines The Async Pattern Async Pattern Basic Implementation Example Dispose Pattern Basic Dispose Pattern Finalizable Types Factories Optional Feature Pattern Template Method Timeouts And in the End A C# Coding Style Conventions 273 A.I General Style Conventions 274

7 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