9780321246752

Direct from the architects themselves, this book is the only source of information on designing reusable APIs in .NET

Figures

xiii

Tables

xv

Foreword

xvii

Preface

xix

Acknowledgments

xxv

About the Authors

xxvii

Introduction

1

(6)

Qualities of a Well-Designed Framework

3

(4)

Well-Designed Frameworks Are Simple

3

(1)

Well-Designed Frameworks Are Expensive to Design

3

(1)

Well-Designed Frameworks Are Full of Trade-Offs

4

(1)

Well-Designed Frameworks Borrow from the Past

5

(1)

Well-Designed Frameworks Are Designed to Evolve

5

(1)

Well-Designed Frameworks Are Integrated

5

(1)

Well-Designed Frameworks Are Consistent

6

(1)

Framework Design Fundamentals

7

(26)

Progressive Frameworks

9

(3)

Fundamental Principles of Framework Design

12

(19)

The Principle of Scenario-Driven Design

13

(6)

The Principle of Low Barrier to Entry

19

(4)

The Principle of Self-Documenting Object Models

23

(6)

The Principle of Layered Architecture

29

(2)

Summary

31

(2)

Naming Guidelines

33

(34)

Capitalization Conventions

34

(7)

Capitalization Rules for Identifiers

34

(2)

Capitalizing Acronyms

36

(3)

Capitalizing Compound Words and Common Terms

39

(2)

Case Sensitivity

41

(1)

General Naming Conventions

41

(7)

Word Choice

42

(1)

Using Abbreviations and Acronyms

43

(1)

Avoiding Language-Specific Names

44

(2)

Naming New Versions of Existing APIs

46

(2)

Names of Assemblies and DLLs

48

(1)

Names of Namespaces

49

(5)

Namespaces and Type Name Conflicts

51

(3)

Names of Classes, Structs, and Interfaces

54

(6)

Names of Generic Type Parameters

56

(1)

Names of Common Types

57

(2)

Naming Enumerations

59

(1)

Names of Type Members

60

(4)

Names of Methods

60

(1)

Names of Properties

61

(2)

Names of Events

63

(1)

Naming Fields

64

(1)

Naming Parameters

64

(1)

Naming Resources

65

(1)

Summary

66

(1)

Type Design Guidelines

67

(38)

Types and Namespaces

69

(5)

Standard Subnamespace Names

73

(1)

Choosing Between Class and Struct

74

(3)

Choosing Between Class and Interface

77

(6)

Abstract Class Design

83

(2)

Static Class Design

85

(1)

Interface Design

86

(3)

Struct Design

89

(2)

Enum Design

91

(10)

Designing Flag Enums

97

(3)

Adding Values to Enums

100

(1)

Nested Types

101

(3)

Summary

104

(1)

Member Design

105

(58)

General Member Design Guidelines

105

(15)

Member Overloading

105

(6)

Implementing Interface Members Explicitly

111

(4)

Choosing Between Properties and Methods

115

(5)

Property Design

120

(5)

Indexed Property Design

122

(2)

Property Change Notification Events

124

(1)

Constructor Design

125

(7)

Type Constructor Guidelines

131

(1)

Event Design

132

(7)

Custom Event Handler Design

138

(1)

Field Design

139

(2)

Operator Overloads

141

(7)

Overloading Operator ==

146

(1)

Conversion Operators

146

(2)

Parameter Design

148

(14)

Choosing Between Enum and Boolean Parameters

150

(2)

Validating Arguments

152

(3)

Parameter Passing

155

(2)

Members with Variable Number of Parameters

157

(4)

Pointer Parameters

161

(1)

Summary

162

(1)

Designing for Extensibility

163

(16)

Extensibility Mechanisms

163

(9)

Unsealed Classes

164

(1)

Protected Members

165

(1)

Events and Callbacks

166

(2)

Virtual Members

168

(2)

Abstractions (Abstract Types and Interfaces)

170

(2)

Base Classes

172

(2)

Sealing

174

(3)

Summary

177

(2)

Exceptions

179

(28)

Exception Throwing

183

(6)

Choosing the Right Type of Exception to Throw

189

(8)

Error Message Design

189

(2)

Exception Handling

191

(4)

Wrapping Exceptions

195

(2)

Using Standard Exception Types

197

(5)

Exception and SystemException

197

(1)

ApplicationException

197

(1)

InvalidOperationException

198

(1)

ArgumentException, ArgumentNullException, and ArgumentOutOfRangeException

198

(1)

NullReferenceException, IndexOutOfRangeException, and AccessViolationException

199

(1)

StackOverflowException

200

(1)

OutOfMemoryException

200

(1)

ComException, SEHException, and other CLR Exceptions

201

(1)

ExecutionEngineException

201

(1)

Designing Custom Exceptions

202

(1)

Exceptions and Performance

203

(2)

Tester-Doer Pattern

203

(1)

Try-Parse Pattern

204

(1)

Summary

205

(2)

Usage Guidelines

207

(28)

Arrays

207

(2)

Attributes

209

(2)

Collections

211

(10)

Collection Parameters

213

(1)

Collection Properties and Return Values

214

(4)

Choosing Between Arrays and Collections

218

(1)

Implementing Custom Collections

219

(2)

ICloneable

221

(1)

IComparable<T> and IEquatable<T>

222

(1)

IDisposable

223

(1)

Object

224

(4)

Object.Equals

224

(1)

Object.GetHashCode

225

(2)

Object.ToString

227

(1)

Uri

228

(2)

System.Uri Implementation Guidelines

229

(1)

System.Xml Usage

230

(1)

Equality Operators

231

(4)

Equality Operators on Value Types

232

(1)

Equality Operators on Reference Types

232

(3)

Common Design Patterns

235

(38)

Aggregate Components

235

(8)

Component-Oriented Design

237

(3)

Factored Types

240

(1)

Aggregate Component Guidelines

240

(3)

The Async Pattern

243

(5)

Async Pattern Basic Implementation Example

247

(1)

Dispose Pattern

248

(12)

Basic Dispose Pattern

251

(5)

Finalizable Types

256

(4)

Factories

260

(4)

Optional Feature Pattern

264

(3)

Template Method

267

(2)

Timeouts

269

(2)

And in the End...

271

(2)

A. C# Coding Style Conventions

273

(8)

General Style Conventions

274

(3)

Brace Usage

274

(1)

Space Usage

275

(1)

Indent Usage

276

(1)

Naming Conventions

277

(1)

Comments

277

(1)

File Organization

278

(3)

B. Using FxCop to Enforce the Design Guidelines

281

(30)

What Is FxCop?

281

(1)

The Evolution of FxCop

282

(1)

How Does It Work?

283

(1)

FxCop Guideline Coverage

284

(27)

FxCop Rules for the Naming Guidelines

284

(9)

FxCop Rules for the Type Design Guidelines

293

(3)

FxCop Rules for Member Design

296

(6)

FxCop Rules for Designing for Extensibility

302

(1)

FxCop Rules for Exceptions

303

(2)

FxCop Rules for Usage Guidelines

305

(4)

FxCop Rules for Design Patterns

309

(2)

C. Sample API Specification

311

(8)

Glossary

319

(4)

Suggested Reading List

323

(4)

Index

327

What is included with this book?

The New copy of this book will include any supplemental materials advertised. Please check the title of the book to determine if it should include any access cards, study guides, lab manuals, CDs, etc.

The Used, Rental and eBook copies of this book are not guaranteed to include any supplemental materials. Typically, only the book itself is included. This is true even if the title states it includes any access cards, study guides, lab manuals, CDs, etc.

This book,Framework Design Guidelines,presents best practices for designing frameworks, which are reusable object-oriented libraries. The guidelines are applicable to frameworks ranging in size and in their scale of reuse: Large system frameworks, such as the .NET Framework, usually consisting of thousands of types and used by millions of developers. Medium-size reusable layers of large distributed applications or extensions to system frameworks, such as the Web Services Enhancements. Small components shared among several applications; for example, a grid control library.It is worth noting that this book focuses on design issues that directly affect the programmability of a framework (publicly accessible APIs 1 ). As a result, we generally do not cover much in terms of implementation details. Just like a user interface design book doesn't cover the details of how to implement hit testing, this book does not describe how to implement a binary sort, for example. This scope allows us to provide a definitive guide for framework designers instead of being yet another book about programming.These guidelines were created in the early days of .NET Framework development. They started as a small set of naming and design conventions but have been enhanced, scrutinized, and refined to a point where they are generally considered the canonical way to design frameworks at Microsoft. They carry the experience and cumulative wisdom of thousands of developer hours over three versions of the .NET Framework. We tried to avoid basing the text purely on some idealistic design philosophies, and we think its day-to-day use by development teams at Microsoft has made it an intensely pragmatic book.The book contains many annotations that explain trade-offs, explain history, amplify, or provide critiquing views on the guidelines. These annotations are written by experienced framework designers, industry experts, and users. They are the stories from the trenches that add color and setting for many of the guidelines presented.To make them more easily distinguished in text, namespace names, classes, interfaces, methods, properties, and types are set in monospace font.The book assumes basic familiarity with .NET Framework programming. A few guidelines assume familiarity with features introduced in version 3.5 of the Framework. If you are looking for a good introduction to Framework programming, there are some excellent suggestions in the Suggested Reading List at the end of the book. Guideline PresentationThe guidelines are organized as simple recommendations usingDo, Consider, Avoid,andDo not.Each guideline describes either a good or bad practice and all have a consistent presentation. Good practices have a check mark in front of them, and bad practices have an ex.The wording of each guideline also indicates how strong the recommendation is. For example, aDoguideline is one that should always 2 be followed. On the other hand,Considerguidelines should generally be followed, but if you fully understand the reasoning behind a guideline and have a good reason to not follow it anyway, you should not feel bad about breaking the rules. Similarly,Do notguidelines indicate something you should almost never do. Less strong,Avoidguidelines indicate that something is generally not a good idea, but there are known cases where breaking the rule makes sense.Some more complex guidelines are followed with additional background information, illustrative code samples, and rationale. Language Choice and Code ExamplesOne of the goals of the Common Language Runtime is to support a variety of programming languages: those with implementations provided by Microsoft, such as C++, VB, C#, F#, Python, and Ruby, as well as third-party languages such as Eiffel, COBOL, Fortran, and others

Amazon no longer offers textbook rentals. We do!

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

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

0321246756

Summary

Table of Contents

Supplemental Materials

Excerpts