Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries (Microsoft .NET Development Series)

• #3 in Best csharp Programming Books

29 Reviews

Sort by: Most Helpful ▲ Date Rating

Depending on your experience with the .NET framework, you may consider the contents of this book as everything from invaluable insights to mildly amusing explanations of a few details of .NET you've always wondered about.

Krzysztof Cwalina and Brad Abrams have worked with designing the public API of the .NET framework from its beginning, and during that process they have compiled a comprehensive guideline for framework design. It is basically this internal guideline they are now publishing as a book.

The text is easy to read and makes for a good reference book. It is littered with more free-form comments from lots of other experts such as Jeffrey Richter, Christopher Brumme, and the occasional comment from Anders Hejlsberg. However, it is mostly reminiscent of a Word document with lots of revision comments liberally sprinkled all over, and I suspect this is how book was made: Take an internal guideline document and polish it off; pass it around to a lot of collegues in Microsoft and ask them to comment on it; incorporate most comments verbatim in the text; and publish.

That said, I still found myself using lots of the little insights in the book in my work in the weeks after having read it. Most of those insights actually came from the free-form comments, so I'm not complaining.

If you use FxCop and are familiar with many of the rules in this tool, most of the guidelines in this book will come as no surprise to you. FxCop was originally a project of Krzysztof's and Brad's designed to automate much of their code review work, so you can learn most of the contents of this book just by using FxCop.

As such, almost all the guidelines in the book are publicly known material, but it's still a well organized reference, and the little extra comments from the authors and lots of other people are what made this book a worthwhile read for me.

I wouldn't consider this book essential reading for .NET developers, but it basically supplements FxCop pretty well.

At Microsoft I work on a development team that has been using the guidelines from this book for nearly 4 years. I am not always a fan of coding standards, thinking they are a necessary evil, often simply arbitrary choices made for consistency.

The Framework Design Guidelines are different. These ensure deep consistency across not just source code, but more importantly the public classes themselves. They include critical, not to be ignored rules on security, cross-language access and localization, as well as the usual good practice type guidelines. But even these "good" practices are always backed with well reasoned argument and examples. As an added bonus FxCop provides a static analysis tool that enforces the guidelines.

Finally, the Framework Design Guidelines provide deep insight into how the .NET Frameworks are designed and used. With the guidelines in mind it is far easier to remember or even guess what classes are provided and how they should be used. This just makes the libraries that much more productive.

Full disclosure: I know Brad and Krzysztof personally, but I would simply remain silent if I didn't think highly of the work.

The .NET framework is still rather new and unfamiliar to many programmers. This book is part of an ongoing series of texts from Microsoft that offers education as to the best use of .NET. The book tackles one of the main problems of computing. Namely, how to write code that will be put into libraries and reused by many others? Arguably, this might even be the central problem in many computing projects.

The guidelines given in the text should strike the reader as very much common sense. Take these, for instance: "Do not require that users perform any extensive initialisation before they can start programming basic scenarios", or "Do provide good defaults for all properties and parameters". If you have programmed in any language, you should readily agree with guidelines like these.

The guidelines also include an excellent discussion about the naming of classes and methods in those classes. This is quite general; applying to any object oriented language like C++ or Java. Indeed, if you program in those languages, consider looking up this chapter of the book for useful hints.

The book also continues a nice practice of the earlier books in the series. It has many sidebars with different people offering informal remarks about the adjoining text. Commentaries that can greatly help your assimilation of the material.

The new book from Brad Abrams and Krzysztof Cwalina is a must-have book for anyone writing .NET and Mono code.


The book includes many of the design guidelines that Brad's blog is famous for. The book is not just a collection of rules, but it also includes the rationale for some of the design decisions and what really makes the book interesting are the commentaries from other developers and architects involved in .NET.

This book is packed with gems.

This book was written by *the* two Microsoft experts on design guidelines for the .NET Framework: Brad Abrams and Krzysztof Cwalina. It really is a MUST read for anybody designing OO class libraries especially libraries that are based on managed code (aka .NET Framework). What I really like is that there are not only "Do", "Do Not", "Avoid", "Consider" guidelines but most of the guidelines are accompanied by annotations from many different folks (Jeff Richter, Rico Mariani, Chris Brumme, Chris Sells, Brent Rector, etc). These annotations really help with the pragmatic side of deciding between conflicting forces. That is, there are many guidelines where you could go one way versus another. The annotations serve to help you decide which way to go. I give it two thumbs way up and even thought it's about 300 pages, it is a quick read.

The title I chose for this review is no cliché. This book earns each and every penny you spend (or have already spent) on it.

I was deceived into thinking that the book was the work of only Cwalina and Abrams and that it's merely a rehash of FxCop guidelines that we have already known and been using for a while now until I read book and encountered the annotations. To have .NET gods (dare I say) like Richter and Hejlsberg contributing suggestions (whether you already knew them or not) in the same book along with other greats like Mariani, Gunnerson, Chris Sells, and Paul Vick to name just a few is simply a slam dunk.

One myth about the book is that it's only useful for folks building APIs. That is so far away from the truth. This book "should" be read by both .NET architects and developers. The suggestions and tips presented in this book can help you write better and more efficient and re-usable code whether it is for a little program or a class library.

And if all this book material was not enough to quench your thirst, the book comes with a bonus: a DVD containing video presentations and seminars on topics related to the book's material (Rico Mariani's presentation is a must see), a sample "real-life" API specification example for the .NET Framework 2.0's System.Diagnostics.StopWatch class, and a .NET 2.0 tool with source code that can be helpful in code reviewing API classes (even though it still has some minor bugs).

This book contains a wealth of material in so small a book and so easy a read that it won't take you too long to read. If you are like me, you would not be able to let go of it before finishing it.

The only take I have on this book is that it should have been available a long time ago, probably when .NET 1.0 was shipped out (blame Microsoft?). It would have helped prevent all the .NET spaghetti that we still see these days.

If this book ever gets any negative reviews, they would probably come from either someone clueless or from someone utterly jealous. It would be naïve to think of this as just a book. Get it, read it, and you'll see for yourself what I mean.

The authors were very modest in choosing their title. Yes, indeed, they focus on the scenario of writing reusable libraries, and write from the perspective of two of the designers of the .NET Framework. However, the utility of this book goes far beyond what the title implies.

If you actually write code,
If you actually design software,
on ANY platform,
and you dreamed of a book of which every page was packed with exceptionally useful, highly pertinent guidelines that will make your designs better and improve nearly every line of code that you write ... then this is that book.

Every recommendation is clearly presented, and the justifications are concisely, effectively and sufficiently argued, with the counterpoints and exceptions noted.

I would pay $5 per page for this book, and have found it to be, by far, the most outstandingly useful technical book I've read.

Two other reviewers have questioned the structure of the book. Do not be misled. The guidance is very well-organized, and super-imposing that organization is not the simple task that it might appear to have been. Also, the style of the book allows the argument for, and the counterpoints, to be presented concisely. If you not only want to know a good way of doing something, but find yourself either wanting to know why it is a good way, or, in your professional life, as a leader of teams, need to articulate why a particular practice is a good practice, then you will especially benefit from it.

In fact, when I was telling my wife how terrific this book is, I said that the style is totally unlike that of my own book, which is more rigid, stodgy and old-school academic--and I greatly envy Krysztof and Brad for having selected and perfected this ideal style for their material.

Another reviewer questioned whether this book is essential. Yes, it most certainly is. In the same way that I want my airline pilots to have pilot's licenses, I want my software development colleagues to have internalized this work.

I found the book immediately helpful. From the first pages, I was able to apply suggestions to how I designed frameworks. I have been creating .Net libraries since 2002. Now as the Lead Architect, my job is to create an entire product framework from the ground up.

My first decision was to ensure that my team had a set of guidelines. I searched the internet and this book came up on Amazon. I purchased the book, and found it immediately helpful. The authors have hand-on experience writing components of the .Net framework. They have learned through trial and error what works best. This book with some minor additions will serve as the guideline for my team.

You will find the book easy to read, clear and concise. In short the specifications of DO, DO NOT, CONSIDER, helped me understand the best practices for creating frameworks. As I read the guidelines, I also uncovered weakness in my understanding, particularly with the 2.0 framework. In these cases, the guidelines served as a target for additional learning.

I agree with the others, this book is not just for .Net frameworks. These are excellent guidelines for any object oriented language; although the book is directly effective for professionals that use the .Net framework.

I don't personally think that all developers will find this book useful. In fact, I have a feeling that some may find it highly useless and disruptive as it is abstract in a sense (one must apply the lessons to each library and scenario independently, taking into consideration many different aspects of usability and readability) and it does require some "retraining" of bad practices which have been long since ingrained due to years of usage.

But whether this book deserves a five star rating or a one star rating - whether this book is for you - can be answered by asking yourself the following question: are you obsessed with quality? Quality in the sense of creating a library that is:

- Easily reused by others, even first timers encountering the library or even first timers to .Net
- Well thought out with well designed classes
- Consistent within itself and consistent with the base libraries from Microsoft

The importance of the little things like naming classes, properties, methods, using one type of construct over another, using one type of accessor over another, etc. cannot be stressed enough in the overall picture of creating a library to a higher standard of quality, usability, and extensibility.

As Confucius is to have said:

"If names be not correct, language is not in accordance with the truth of things. If language be not in accordance with the truth of things, affairs cannot be carried on to success.

"When affairs cannot be carried on to success, proprieties and music do not flourish. When proprieties and music do not flourish, punishments will not be properly awarded. When punishments are not properly awarded, the people do not know how to move hand or foot.

"Therefore a superior man considers it necessary that the names he uses may be spoken appropriately, and also that what he speaks may be carried out appropriately. What the superior man requires is just that in his words there may be nothing incorrect."

As I wrote in an e-mail to my team, I think that digesting this book will lead to: higher quality public facing APIs for our customer development teams seeking to extend the functionality, increased readability and more consistency internally in our teams, increased usability and decreased maintenance costs for the support teams as well as new developers on our team, and of course, increased skill, knowledge, and competency as developers of each of the team members.

This is a must read for every .NET architect and developer. These guys have taken their experience over the 3 releases of the .NET framework and put it all into one place for us. This book won't leave my side.

It is put together very well, has some excellent insight into the minds of the team that has been working so hard to get us a "powerful and simplistic" framework to work with.

If you are doing Product Line Engineering or Framework building, this book is an awesome reference.

In my role as CTO of a software firm, many developers ask me 'what can I do to move up to the architect/team lead role'.

Unfortunately it has as much to do with 'soft skills' in many cases and hard ones. Not good with people? It will be tough no matter what you read. This book however, is mandatory in my opinion if you are in this domain (and even in others as it is such an excellent example of what building a good reusable framework is all about, be it Java, COBOL or C#).

I would like to add something I believe others have missed. Although this book covers one dimension, you really need to cover the 'Domain Driven Design and Development' aspect for true optimal OO Framework reuse. Although this book is excellent, it should be supplemented with Eric Evan's work on Domain Driven Design in my strong opinion. Otherwise the full benefit would not be reached. This also adds complexity as it is assumed that an ORM framework is used, which today (early September 2007) means NHibernate. Perhaps some day Linq to Entities will work, but NHibernate is really a non-optional aspect now in reusable framework development (as are Mock frameworks, inversion of control and dependency injection, automated build server infrastructure, and much more that NEITHER book covers).

It's not for everyone, especially the lone wolf writing in his garage in a team of 1. If you have any code that would ever even have the chance of being reused (and even if you do not, you should write code such that it will), and if you are on a team of 2 or more, it is very, very hard not to implore you to read this.

Kind Regards,
Damon Carr

Even though this book has ".NET" in the name, it really reaches way beyond .NET and applies equally to Java or any other high-level object oriented language. Also, it is not just architects or designers who should read this book. Every developer trying to understand or even just use any kind of framework will benefit from it and gain deeper understanding why things are built the way they are built. Besides, the time comes in life of every developer when all of a sudden you must write your first framework, a set of base classes or whatever shared piece of code. At this moment you will thank yourself for having read this book (and still having it at reach if possible).

WARNING: this book requires some previous knowledge of object-oriented programming and familiarity with a C-like language (code samples are in C#, but any similar language will do). Also, keep in mind that this book is about design and concepts and not about C# or any particular .NET framework feature (although one can pick up some very useful tips along the way).

This is one of the two books that haven't left my desk ever since I bought them (the other one being "Head First Design Patterns" from Eric and Elisabeth Freeman).

Yes, the title's a mouthful, but it's also well worth a purchase. Although it's generally focused on helping you develop public APIs (i.e. those that are going to be exposed to customers or other teams), it's also a superb reference if you just want to know the correct methodology behind many aspects of .NET development, such as the best method to use when handling exceptions for example.

Common to this book and the Standard Library Annotated Reference titles (also published by Addison Wesley) are the comments from developers, experts and the original authors of the .NET framework themselves, interspersed throughout the main text. These little gems help split the text up, give background details on certain features and can even describe how what ended up shipping was actually dead wrong in retrospect. They're in a conversational style that's refreshing and really aid the understanding of some of the topics. There's even disagreement at times, with annotations appearing one after another, weighing the pros and cons of particular approaches. There's always the danger that a title like this could feel overly prescriptive, but that's definitely not the case here.

The main text is well written and the coverage of topics is just right. It never feels like a boring tome; instead there's genuine insight on the majority of pages with no fluff to speak of. The guidelines themselves come split into Do, Do Not, Avoid and Consider forms, where the first three are strong recommendations and the Consider is a guideline that applies the majority of the time, but is looser than the others. The guidelines always have supporting code examples and, although I thought I was a reasonable .NET programmer, I found myself learning a great deal about how to code correctly against the framework and how to better design my classes, both internal and those that will get used by others.

The book also includes suggested naming conventions (which is always a near religious thing in developer circles, and which I found myself disagreeing with at many points), a sample API design for the .NET 2.0 Stopwatch class (which is great, but all too brief) and a bit of a pointless guide to FxCop, which feels a little like filler material. At around 300 pages, the book is accessible (i.e. you're not going to break your back hefting it around the office), but you're better off picking up the title from Amazon.com where it's significantly cheaper than getting it from the UK site (at $24 instead of a rip-off £28.50).

Completing the package is a DVD with code samples, the exact same Stopwatch API review (why?), and quite a few lecture videos from the people who wrote the book and other .NET luminaries like performance whiz Rico Mariani (who talks very fast, like it's costing him valuable cycles to include any space between his words!), FxCop dev Michael Murray and Steven Clarke.

This one's a keeper.

The book is essentially about designing good API based on the lessons learned when designing the .NET Framework. A good knowledge of the CLR is assumed and in particular C#. Most of the examples are in C# syntax with some in VB.NET. The book takes what could be very dry material and makes it more interesting and useful with real examples from the current CLR and anecdotal information from various well known names in the .NET world.

There are 9 chapters and 3 Appendices with information on style conventions, the FxCop tool and a sample API.
The first 7 chapters are well-structured and very readable, even start-to-finish. They can also be easily used as reference material focusing on specifics such as naming guidelines, type and member design and exception class design. The last two chapters cover general usage guidelines and common design patterns. These topics are very broad and consequently the chapters feel more like summary info and don't go into much depth. Picking up some titles from the suggested reading list is definitely recommended to augment these chapters if you are interested in more detail.

Overall the book is readable and straightforward and should help anyone writing .NET libraries produce more usable APIs. Certainly the guidelines are mostly covered by FxCop but the additional information around the 'why' for the rules should help you fix the violations in the right way.

Excerpt from C# Online.NET Review (wiki.CSharp-Online.NET):
"The book is a codification of the set of guidelines worked out by the Microsoft .NET Framework development team to govern the project. It has been refined over six years. It's like the Constitution of .NET. But, the guidelines are so well crafted that the principles embodied in them apply equally well, not only, to all .NET languages, but also, to Java or any object-oriented language."

As an outstanding member of the Microsoft .NET development series from Addison Wesley, this book examines the core issues you should address when designing public APIs with plenty of examples in C#.

After dealing with some general design principles and the philosophy behind the design of the Microsoft .NET Framework, the core of this book revolves around consistency guidelines for the .NET API design, from naming conventions (when to use Pascal casing and when to use camel casing) to the proper use of exceptions, from where to choose structs, classes, or interfaces to how to use properties, events, and operator overloads.

If you work with .NET, this book is an invaluable resource that explains the rationale behind the proposed guidelines. If you don't, you can still benefit from many of the guidelines.

Many comments from distinguished Microsoft employees make of this book an easy-to-read document you will surely enjoy. They even tell you where their designs were not right when they shipped the .NET Framework and, due to backward compatibility requirements, they were forced to live with their mistakes.

Framework Design Guidelines offers a wealth of information that is presented in a format that is easy to understand and offers insights from various developers at Microsoft. Comment boxes are sprinkled throughout the book, written by Microsoft .NET team members and other expert developers in .NET. Sometime one, but often two, three of four comments will follow a core concept in the book. They offer up insights, criticisms and great real-world examples of how the design guidelines have helped the .NET, and where ignore them hurt .NET. To me, this communication directly from the actual developers who wrote numerous classes in the 1.0, 1.1 and 2.0 releases is great. And sometimes they will disagree on a point, which really provides insights into when and how you should follow the guidelines.

I am already starting to present ideas from this book to my team at work. This will influence our next product release in a very good way.

This book is not just for people developing frameworks but also for Application programmers who use frameworks. If you donot know how frameworks are designed then you wont be really efficient in using it.

I also use thier Naming Guidelines in our software development team just to create a standard. Overall a class work. Kudos to Brad et al.

It's not often that I see a book like this, and I do so with pleasure. This book covers best practices in developing frameworks and APIs for .NET. And it comes from a variety of different sources and perspectives. There is excellent pragmatic advice in here and it's worth a read even if you aren't doing .NET.

There is only one part of the book that I wasn't completely satisfied with: the coding style conventions. Why? Because I try to follow these kinds of suggested standards, but these are not the default settings in Visual Studio! Who makes this stuff up by the way? No spaces between arguments??? C'mon. Also, I'll "raise" an event, but I won't throw an exception if someone says "fire" an event. Let it go. :-)

That being said...This is a great read for anyone who writes classes in .NET at all even though the objective is writing public APIs. If everyone designed this way, we'd all be a bunch of happy .NET developers.

Probably the most indispensible book in the .NET Development Series (except for my book, of course), the Framework Design Guidelines provides a huge amount of information for the .NET library developer. Most useful will be the guidance around how best to design .NET libraries, culled from the huge amount of experience that Microsoft has with building the Framework itself. Also helpful are the annotations from the designers and implementers of the Framework, shedding light on the design decisions and thought processes behind .NET itself. Highly recommended!

-- (...)

Simply invaluable.

This book encompasses everything a developer that has to design a piece of software needs in order to remain consistent with the rest of the .NET Framework and therefore make their API easily understandable and usable.

This book doesn't teach you how to use the .NET Framework. It doesn't teach you any language. It doesn't teach you tips and tricks.
What it does is teach you what you need to consider whenever you design anything in .NET. If I had it my way, I would make it so that wherever I worked - this would be required reading for anyone with enough experience to start designing software.

The only caveat is that there are a couple of guidelines there that are arguable, like the creation of new replacement types with numerical suffixes (see the TimeZone2 debate). However, 99% of everything written in the book is written in stone.

This is an extremely valuable multi-faceted discussion of how to name your classes and methods -- and how to structure your interfaces for ease of use and evolution over time.

The authors are thoughtful and clear in their reasoning and highlight their own "lessons learned" with real examples of shipped code that in retrospect could have been done better.

Book has perfect guidelines for the "layout" of designing a framework.

Very well organized, and good content.
Id like to see more diagrams or so, so we can se how they decide to build the things... but it still is great.

I think this is one of the best books on this subject that I have read so far- very practical, very useful. There is a lot of information, real-life examples and experience from the .NET framework design team.

As a professional I have worked many times on building re-usable and extensible frameworks. Therefore, I had to read several books in order to make sure that the framework I was building was doing what it was supposed to do. However, in all these years I had never the luck to get a complete guide of "building a framework the right way" and I had to always put together pieces from different articles in order to make my own guide. Well, there you have it! Buy this book, read it and you will have a complete guide of how to do things the right way. Another great thing about this book is that different professionals make their comments about almost every guideline. As a result you are not only exposed to writer's view but also to the views and opinions of many well respected software professionals. Do buy this book and as hard as it might seem try to apply its recommendations to your daily development process.

If you need to write C#/.Net or even Java, this book is a must have.

Since I do a lot of framework programming for .NET, this is a great book. In fact, I consider some of the conventions listed in this book to be good practice even when not using .NET.