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

by Cwalina, Krzysztof; Abrams, Brad

• ISBN13: 9780321246752
• ISBN10: 0321246756
• Edition: DVD
• Format: Hardcover w/Disk
• Copyright: 2006-01-01
• Publisher: Addison-Wesley Professional

Summary

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

Table of Contents

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

Excerpts

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