Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries

Table of Contents:

Figures.

Acknowledgments.

About the Authors.

Tables.

Foreword.

Preface.

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

      Well-Designed Frameworks Borrow from the Past

      Well-Designed Frameworks Are Designed to Evolve

      Well-Designed Frameworks Are Integrated

      Well-Designed Frameworks Are Consistent

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

      The Principle of Layered Architecture

    Summary

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

      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

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

    Struct Design

    Enum Design

      Designing Flag Enums

      Adding Values to Enums

    Nested Types

    Summary

5. 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

6. Designing for Extensibility.

    Extensibility Mechanisms

      Unsealed Classes

      Protected Members

      Events and Callbacks

      Virtual Members

      Abstractions (Abstract Types and Interfaces)

    Base Classes

    Sealing

    Summary

7. 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

      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

8. Usage Guidelines.

    Arrays

    Attributes

    Collections

      Collection Parameters

      Collection Properties and Return Values

      Choosing Between Arrays and Collections

      Implementing Custom Collections

    ICloneable

    IComparable and IEquatable

    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

9. 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 ...

Appendix A: C# Coding Style Conventions.

     General Style Conventions

       Brace Usage

       Space Usage

       Indent Usage

     Naming Conventions

     Comments

     File Organization

Appendix B: Using FxCop to Enforce the Design Guidelines.

     What Is FxCop?

     The Evolution of FxCop

     How Does It Work?

    FxCop Guideline Coverage

      FxCop Rules for the Naming Guidelines

      FxCop Rules for the Type Design Guidelines

      FxCop Rules for Member Design

      FxCop Rules for Designing for Extensibility

      FxCop Rules for Exceptions

      FxCop Rules for Usage Guidelines

      FxCop Rules for Design Patterns

Appendix C: Sample API Specification.

Glossary.

Suggested Reading List.

Index.