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

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

Released September 2005
Publisher(s): Addison-Wesley Professional
ISBN: 9780321246752

Read it now on the O’Reilly learning platform with a 10-day free trial.

O’Reilly members get unlimited access to books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial

Book description

A new edition of this title is available, ISBN-10: 0321545613 ISBN-13: 9780321545619

"This book is an absolute must-read for all .NET developers. It gives clear do and don't guidance on how to design class libraries for .NET. It also offers insight into the design and creation of .NET that really helps developers understand the reasons why things are the way they are. This information will aid developers designing their own class libraries and will also allow them to take advantage of the .NET class library more effectively."

--Jeffrey Richter, author/trainer/consultant, Wintellect

"Framework Design Guidelines will help you in two important ways. First, any .NET developer will benefit from a greater understanding of the design principles that govern the .NET Base Class Library. Second, a deeper understanding of these principles will help you to create software that integrates well with the .NET environment. Quite frankly, this book should be on every .NET developer's bookshelf."

--Bill Wagner, founder and consultant, SRT Solutions, author of Effective C#

"Not since Brooks' The Mythical Man Month has the major software maker of its time produced a book so full of relevant advice for the modern software developer. This book has a permanent place on my bookshelf and I consult it frequently."

--George Byrkit, senior software engineer, Genomic Solutions

"This book is a must-read for all architects and software developers thinking about frameworks. The book offers insight into some driving factors behind the design of the .NET Framework. It should be considered mandatory reading for anybody tasked with creating application frameworks."

--Peter Winkler, senior software engineer, Balance Technology Inc.

"Frameworks are valuable but notoriously difficult to construct: Your every decision must be geared towards making them easy to be used correctly and difficult to be used incorrectly. This book takes you through a progression of recommendations that will eliminate many of those downstream 'I wish I'd known that earlier' moments. I wish I'd read it earlier."

--Paul Besly, principal technologist, QA

"Filled with information useful to developers and architects of all levels, this book provides practical guidelines and expert background information to get behind the rules. Framework Design Guidelines takes the already published guidelines to a higher level, and it is needed to write applications that integrate well in the .NET area."

--Cristof Falk, software engineer

Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries teaches developers the best practices for designing system frameworks and reusable libraries for use with the Microsoft .NET Framework and WinFX. This book focuses on the design issues that directly affect the programmability of a framework, specifically its publicly accessible APIs.

This book can improve the work of any .NET developer producing code that other developers will use. An added benefit is a collection of annotations to the guidelines by various members of the Microsoft .NET Framework and WinFX teams, which provide a lively discussion of the motives behind the guidelines, along with examples of good reasons for breaking the guidelines.

Microsoft architects Krzysztof Cwalina and Brad Abrams offer guidelines for framework design from the top down. From their long experience and deep insight, you will learn

  • The general philosophy of framework design

  • Principles and guidelines that are fundamental to overall framework design

  • Naming guidelines for the various parts of a framework, such as namespaces, types, and members

  • Guidelines for the design of types and members of types

  • Issues and guidelines that are important to ensure appropriate extensibilityin your framework

  • Guidelines for working with exceptions, the preferred error reporting mechanism in the .NET Framework and WinFX

  • Guidelines for extending and using types that commonly appear in frameworks

  • Guidelines for and examples of common framework design patterns

Guidelines in this book come in four major forms: Do, Consider, Avoid, and Do not. In general, a Do guideline should almost always be followed, a Consider guideline should generally be followed, an Avoid guideline indicates that something is generally not a good idea, and a Do not guideline indicates something you should almost never do. Every guideline includes a discussion of its applicability, and most guidelines include a code example.

A companion DVD includes the Designing .NET Class Libraries video series, instructional presentations by the authors on design guidelines for developing classes and components that extend the .NET Framework. A sample API specification and other useful resources are also included.

Table of contents

  1. Copyright
    1. Dedication
  2. Microsoft .NET Development Series
    1. Titles in the Series
  3. Figures
  4. Tables
  5. Foreword
  6. Preface
    1. Guideline Presentation
    2. Language Choice and Code Examples
    3. About This Book
  7. Acknowledgments
  8. About the Authors
  9. About the Annotators
  10. 1. Introduction
    1. 1.1. Qualities of a Well-Designed Framework
      1. 1.1.1. Well-Designed Frameworks Are Simple
      2. 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.4. Well-Designed Frameworks Borrow from the Past
      5. 1.1.5. Well-Designed Frameworks Are Designed to Evolve
      6. 1.1.6. Well-Designed Frameworks Are Integrated
      7. 1.1.7. Well-Designed Frameworks Are Consistent
  11. 2. Framework Design Fundamentals
    1. 2.1. Progressive Frameworks
    2. 2.2. Fundamental Principles of Framework Design
      1. 2.2.1. The Principle of Scenario-Driven Design
        1. 2.2.1.1. Usability Studies
      2. 2.2.2. The Principle of Low Barrier to Entry
      3. 2.2.3. The Principle of Self-Documenting Object Models
        1. 2.2.3.1. Naming
        2. 2.2.3.2. Exceptions
        3. 2.2.3.3. Strong Typing
        4. 2.2.3.4. Consistency
        5. 2.2.3.5. Limiting Abstractions
      4. 2.2.4. The Principle of Layered Architecture
        1. 2.2.4.1. Exposing Layers in Separate Namespaces
        2. 2.2.4.2. Exposing Layers in the Same Namespace
    3. 2.3. Summary
  12. 3. Naming Guidelines
    1. 3.1. Capitalization Conventions
      1. 3.1.1. Capitalization Rules for Identifiers
      2. 3.1.2. Capitalizing Acronyms
      3. 3.1.3. Capitalizing Compound Words and Common Terms
      4. 3.1.4. Case Sensitivity
    2. 3.2. General Naming Conventions
      1. 3.2.1. Word Choice
      2. 3.2.2. Using Abbreviations and Acronyms
      3. 3.2.3. Avoiding Language-Specific Names
      4. 3.2.4. Naming New Versions of Existing APIs
    3. 3.3. Names of Assemblies and DLLs
    4. 3.4. Names of Namespaces
      1. 3.4.1. Namespaces and Type Name Conflicts
        1. 3.4.1.1. Application Model Namespaces
        2. 3.4.1.2. Infrastructure Namespaces
        3. 3.4.1.3. Core Namespaces
        4. 3.4.1.4. Technology Namespace Groups
    5. 3.5. Names of Classes, Structs, and Interfaces
      1. 3.5.1. Names of Generic Type Parameters
      2. 3.5.2. Names of Common Types
      3. 3.5.3. Naming Enumerations
    6. 3.6. Names of Type Members
      1. 3.6.1. Names of Methods
      2. 3.6.2. Names of Properties
      3. 3.6.3. Names of Events
      4. 3.6.4. Naming Fields
    7. 3.7. Naming Parameters
    8. 3.8. Naming Resources
    9. 3.9. Summary
  13. 4. Type Design Guidelines
    1. 4.1. Types and Namespaces
      1. 4.1.1. Standard Subnamespace Names
        1. 4.1.1.1. The .Design Subnamespace
        2. 4.1.1.2. The .Permissions Subnamespace
        3. 4.1.1.3. The .Interop Subnamespace
    2. 4.2. Choosing Between Class and Struct
    3. 4.3. Choosing Between Class and Interface
    4. 4.4. Abstract Class Design
    5. 4.5. Static Class Design
    6. 4.6. Interface Design
    7. 4.7. Struct Design
    8. 4.8. Enum Design
      1. 4.8.1. Designing Flag Enums
      2. 4.8.2. Adding Values to Enums
    9. 4.9. Nested Types
    10. 4.10. Summary
  14. 5. Member Design
    1. 5.1. General Member Design Guidelines
      1. 5.1.1. Member Overloading
      2. 5.1.2. Implementing Interface Members Explicitly
      3. 5.1.3. Choosing Between Properties and Methods
    2. 5.2. Property Design
      1. 5.2.1. Indexed Property Design
      2. 5.2.2. Property Change Notification Events
    3. 5.3. Constructor Design
      1. 5.3.1. Type Constructor Guidelines
    4. 5.4. Event Design
      1. 5.4.1. Custom Event Handler Design
    5. 5.5. Field Design
    6. 5.6. Operator Overloads
      1. 5.6.1. Overloading Operator ==
      2. 5.6.2. Conversion Operators
    7. 5.7. Parameter Design
      1. 5.7.1. Choosing Between Enum and Boolean Parameters
      2. 5.7.2. Validating Arguments
      3. 5.7.3. Parameter Passing
      4. 5.7.4. Members with Variable Number of Parameters
      5. 5.7.5. Pointer Parameters
    8. 5.8. Summary
  15. 6. Designing for Extensibility
    1. 6.1. Extensibility Mechanisms
      1. 6.1.1. Unsealed Classes
      2. 6.1.2. Protected Members
      3. 6.1.3. Events and Callbacks
      4. 6.1.4. Virtual Members
      5. 6.1.5. Abstractions (Abstract Types and Interfaces)
    2. 6.2. Base Classes
    3. 6.3. Sealing
    4. 6.4. Summary
  16. 7. Exceptions
    1. 7.1. Exception Throwing
    2. 7.2. Choosing the Right Type of Exception to Throw
      1. 7.2.1. Error Message Design
      2. 7.2.2. Exception Handling
      3. 7.2.3. Wrapping Exceptions
    3. 7.3. Using Standard Exception Types
      1. 7.3.1. Exception and SystemException
      2. 7.3.2. ApplicationException
      3. 7.3.3. InvalidOperationException
      4. 7.3.4. ArgumentException, ArgumentNullException, and ArgumentOutOfRangeException
      5. 7.3.5. NullReferenceException, IndexOutOfRangeException, and AccessViolationException
      6. 7.3.6. StackOverflowException
      7. 7.3.7. OutOfMemoryException
      8. 7.3.8. ComException, SEHException, and other CLR Exceptions
      9. 7.3.9. ExecutionEngineException
    4. 7.4. Designing Custom Exceptions
    5. 7.5. Exceptions and Performance
      1. 7.5.1. Tester-Doer Pattern
      2. 7.5.2. Try-Parse Pattern
    6. 7.6. Summary
  17. 8. Usage Guidelines
    1. 8.1. Arrays
    2. 8.2. Attributes
    3. 8.3. Collections
      1. 8.3.1. Collection Parameters
      2. 8.3.2. Collection Properties and Return Values
        1. 8.3.2.1. Snapshots Versus Live Collections
      3. 8.3.3. Choosing Between Arrays and Collections
      4. 8.3.4. Implementing Custom Collections
        1. 8.3.4.1. Naming Custom Collections
    4. 8.4. ICloneable
    5. 8.5. IComparable<T> and IEquatable<T>
    6. 8.6. IDisposable
    7. 8.7. Object
      1. 8.7.1. Object.Equals
        1. 8.7.1.1. Equals on Value Types
        2. 8.7.1.2. Equals on Reference Types
      2. 8.7.2. Object.GetHashCode
      3. 8.7.3. Object.ToString
    8. 8.8. Uri
      1. 8.8.1. System.Uri Implementation Guidelines
    9. 8.9. System.Xml Usage
    10. 8.10. Equality Operators
      1. 8.10.1. Equality Operators on Value Types
      2. 8.10.2. Equality Operators on Reference Types
  18. 9. Common Design Patterns
    1. 9.1. Aggregate Components
      1. 9.1.1. Component-Oriented Design
      2. 9.1.2. Factored Types
      3. 9.1.3. Aggregate Component Guidelines
    2. 9.2. The Async Pattern
      1. 9.2.1. Async Pattern Basic Implementation Example
    3. 9.3. Dispose Pattern
      1. 9.3.1. Basic Dispose Pattern
      2. 9.3.2. Finalizable Types
    4. 9.4. Factories
    5. 9.5. Optional Feature Pattern
    6. 9.6. Template Method
    7. 9.7. Timeouts
    8. 9.8. And in the End...
  19. A. C# Coding Style Conventions
    1. A.1. General Style Conventions
      1. A.1.1. Brace Usage
      2. A.1.2. Space Usage
      3. A.1.3. Indent Usage
    2. A.2. Naming Conventions
    3. A.3. Comments
    4. A.4. File Organization
  20. B. Using FxCop to Enforce the Design Guidelines
    1. B.1. What Is FxCop?
    2. B.2. The Evolution of FxCop
    3. B.3. How Does It Work?
    4. B.4. FxCop Guideline Coverage
      1. B.4.1. FxCop Rules for the Naming Guidelines
        1. B.4.1.1. FxCop Rules for Capitalization Conventions
        2. B.4.1.2. FxCop Rules for General Naming Conventions
        3. B.4.1.3. FxCop Rules for Names of Assemblies and DLLs
        4. B.4.1.4. FxCop Rules for Names of Namespaces
        5. B.4.1.5. FxCop Rules for Names of Classes, Structs, and Interfaces
        6. B.4.1.6. FxCop Rules for Names of Type Members
        7. B.4.1.7. FxCop Rules for Naming Parameters
        8. B.4.1.8. FxCop Rules for Naming Resources
      2. B.4.2. FxCop Rules for the Type Design Guidelines
        1. B.4.2.1. FxCop Rules for Types and Namespaces
        2. B.4.2.2. FxCop Rules for Choosing Between Class and Struct
        3. B.4.2.3. FxCop Rules for Choosing Between Class and Interface
        4. B.4.2.4. FxCop Rules for Interface Design
        5. B.4.2.5. FxCop Rules for Struct Design
        6. B.4.2.6. FxCop Rules for Enum Design
        7. B.4.2.7. FxCop Rules for Nested Types
      3. B.4.3. FxCop Rules for Member Design
        1. B.4.3.1. FxCop Rules for General Member Design Guidelines
        2. B.4.3.2. FxCop Rules for Property Design
        3. B.4.3.3. FxCop Rules for Constructor Design
        4. B.4.3.4. FxCop Rules for Event Design
        5. B.4.3.5. FxCop Rules for Field Design
        6. B.4.3.6. FxCop Rules for Operator Overloads
        7. B.4.3.7. FxCop Rules for Parameter Design
      4. B.4.4. FxCop Rules for Designing for Extensibility
        1. B.4.4.1. FxCop Rules for Extensibility Mechanisms
        2. B.4.4.2. FxCop Rules for Base Classes
        3. B.4.4.3. FxCop Rules for Sealing
      5. B.4.5. FxCop Rules for Exceptions
        1. B.4.5.1. FxCop Rules for Exception Throwing
        2. B.4.5.2. FxCop Rules for Choosing the Right Type of Exception to Throw
        3. B.4.5.3. FxCop Rules for Using Standard Exception Types
        4. B.4.5.4. FxCop Rules for Designing Custom Exceptions
      6. B.4.6. FxCop Rules for Usage Guidelines
        1. B.4.6.1. FxCop Rules for Arrays
        2. B.4.6.2. FxCop Rules for Attributes
        3. B.4.6.3. FxCop Rules for Collections
        4. B.4.6.4. FxCop Rules for Object
        5. B.4.6.5. FxCop Rules for Uri
        6. B.4.6.6. FxCop Rules for System.Xml Usage
        7. B.4.6.7. FxCop Rules for Common Operators
      7. B.4.7. FxCop Rules for Design Patterns
  21. C. Sample API Specification
    1. Specification: .NET Framework, Stopwatch
      1. Executive Overview
    2. 1. Requirements
    3. 2. API Specification
      1. 2.1. Scenarios
        1. 2.1.1. Measure Time Elapsed
        2. 2.1.2. Measure Time Elapsed (Simplified)
        3. 2.1.3. Reuse Stopwatch (VB)
        4. 2.1.4. Measure Cumulative Intervals
      2. 2.2. API Design
    4. 3. Functional Specification
  22. Glossary
  23. Suggested Reading List
    1. Web Sites
    2. Blogs
  24. DVD-ROM Warranty

Product information

  • Title: Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries
  • Author(s):
  • Release date: September 2005
  • Publisher(s): Addison-Wesley Professional
  • ISBN: 9780321246752