Book Review: Framework Design Guidelines by Krzysztof Cwalina & Brad Abrams

I’ve been reading Brad’s blog for, well, as long as I’ve been reading blogs. I always found great little tidbits of .NET knowledge on his blog: performance tips, Framework conventions and idioms, as well as pointers into the .NET Design Guidelines. So when this book, Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries was announced, I was pretty excited about it; as soon as it came out, I made sure I got my hands on a copy. This book gives advice for programmers designing .NET libraries so that they resemble the .NET framework itself, allowing other programmers to pick it up more easily.

The book is very succinct, which I like. It’s arranged like a functional specification with chapters, headings, sub-headings, sub-sub-headings… Every section has a number and a title. It’s very orderly making it easy to read: everything is in digestable little chunks. With only nine chapters and topping out a lean and mean 327 pages including Annexes, the book has a very tight focus. For each section, they have a set of advice codified in quick little comments: DOs, DO NOTs, CONSIDERs, and AVOIDs. The bold highlights for those points make it easy to find when looking this up as a reference.

Like I mentioned at the beginning, I’ve been reading Brad’s blog for a couple of years (Krzysztof’s for about a year). I’ve also been using FxCop for a while on my projects, so a lot of the advice was already familiar to me, although there were a number of times that I went: “Oh yeah! I remember that.” Even still, I definitely learned something in every section. I also appreciated, even though .NET 2.0 hasn’t shipped yet, advice on generics; it means the book will last at least another version of the framework, probably more. The most helpful thing about the book were the annotations for the guidelines by Brad, Krzysztof, and other programmers both from within Microsoft and without. Those sections were great for two reasons: 1) since it reads like a technical document, the annotations put a human face on the writing; and 2) they point out where they screwed up the framework. All the little warts on the framework: misnamed classes, inappropriate interfaces, Exception types that are useless (like ApplicationException) are outlined in the text. That’s really good: it shows that these guys really care about putting out a great product and that creating a framework is f-ing hard; there’s a lot to consider. I recommend you follow all their advice. I’ve been trying to follow the guidelines for my project at work. Following the advice makes it a lot easier to version my framework and it makes it more .NET-like, so I can save time on documentation ;). I only disagree with one section on System.Uri for a special, but important, case that I happen to be stuck in. (Say, that sounds like a good idea for a blog post.)

I heartily recommend this book if you’re developing in .NET; even if you’ve got a one-project solution and you’re only using Framework classes (i.e. you’re not developing a framework), this book will benefit your efforts. If you are developing a framework targetting .NET, this should be mandatory reading.

DO buy this book.

DO read it cover to cover

DO review it periodically.

AVOID other books that claim to help you with this stuff. (More to follow on that.)