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

It has already been several months since I purchased the book Framework Design Guidelines by Krzysztof Cwalina and Brad Abrams. Since that time it proved itself to be invaluable. When you design or write reusable libraries or are concerned with the quality and usability of your API, this book is for you.

The subtitle says it all; this book describes conventions, idioms, and patterns for reusable .NET libraries. It includes the following topics:

  • Naming Guidelines. How to name assemblies, namespaces, types and members;
  • Type Design Guidelines. How to design abstract and static classes, interfaces, structs, enums, and nested types and how to choose between classes, structs, and interfaces;
  • Member Design. How to design properties, constructors, events, fields and parameters;
  • Designing for Extensibility. How to make a framework extensible without painting yourself in a corner;
  • Exceptions. When and how to throw and catch exceptions;
  • Usage Guidelines. How to use arrays, attributes, collections, and usage and caveats of System.Object's common members;
  • Common Design Patterns. Describes a very limited set of patterns that are used frequently in the .NET framework, like the async and dispose patterns.

The book’s guidelines consist of 487 do, consider, avoid, and do not recommendations. Here are four examples of the book’s advice.

DO validate arguments passed to public, protected, or explicitly implemented members. Throw System.ArgumentException, or one of its subclasses, if the validation fails.
CONSIDER providing simple, ideally default, constructors.
AVOID implementing interface members explicitly without having a strong reason to do so.
DO NOT make members virtual unless you have a good reason to do so and you are aware of all the costs related to designing, testing, and maintaining virtual members.

I found this book very easy to read with it's clear do and don't guidance. I especially loved the comments by experts like Anders Hejlsberg, Eric Gunnerson, Rico Mariani, Joe Duffy, and many more. These notes stick out like yellow Post-its with comments on almost every guideline in the book. In these comments the annotators not only describe the how and why of the guidelines, but also admit to design flaws in the .NET framework itself. But please don’t be misled. The book doesn’t talk about the base class library (BCL), doesn’t tell you how to improve the quality of your code, and doesn’t dictate how to case your private class members and where to place curly braces. It focuses on design issues that directly affect the programmability of a framework.

The book made me much more conscious of the way I design my classes. While I’m mostly writing application code instead of reusable frameworks, I believe it still is extremely important that code communicates it’s intend and that programmers using your classes are able to write really simple, readable and safe code. The quality of my design has improved significantly over the last half year because of this book. After my good personal experiences with the book I recently advised my team, in a meeting about code conventions, to strictly follow the Framework Design Guidelines. As a result a summary of the book is now one of the leading documents in the teams coding conventions.

In my opinion every .NET development team should own at least one copy of this book and review code using this book as guidance. However, the book does not replace your in-company coding guidelines. Like I said, the book doesn’t dictate coding guidelines. Nevertheless, this book is the foundation your company's guidelines should refer to. (Another useful book that might help writing your in-house guidelines is Code Complete, Second Edition by Steve McConnell).

While Framework Design Guidelines doesn't dictate a coding style it contains an appendix in which the writers suggest C# coding style conventions. In contrast with the great guidelines in the book, these suggestions seem very odd to me. The suggested coding style is quite different from the default style used by Microsoft and the formatting within Visual Studio. One of the writers, Brad Abrams, published C# guidelines on his blog complying with ‘the standards’ rather than the suggestions in his book, making the style used in the appendix even more queer. So, in style with the book’s guidelines I can recommend the following:

AVOID using the suggested C# coding style conventions given by Framework Design Guidelines.

A very well-considered guideline I can recommend is the IDesign C# Coding Standard by a company called IDesign.

CONSIDER using the IDesign C# Coding Standard.

What I also recommend is watching two videos of Krzysztof Cwalina about framework design. The first video is a three hours lecture held in January 2007 at Microsoft Research Center. Krzysztof basically summarizes Framework Design Guidelines while giving interesting anecdotes. The second video is a presentation from TechEd 2007 last November. This presentation gives a broader look at the processes that affect the design of frameworks. In this video Cwalina proposes some interesting guidelines, such as:

  • Manage your assembly and type dependencies;
  • Keep abstractions (abstract types etc.) as simple as possible;
  • Design a type as either a primitive, an abstraction or a library. Do not mix;
  • Balance advances with compatibility, because breaking changes to frameworks can't be taken lightly, and:
  • Avoid duplication and overlap.

A good example of the content you might find in Framework Design Guidelines is the Dispose, Finalization, and Resource Management guideline on Joe Duffy's blog. It contains a guideline that's much more complete (and advanced) than the one you'll find in Framework Design Guidelines, but it gives you a clear indication of the book's writing style with it's do's, don'ts and annotations.

Recently Krzysztof and Brad announced working on a second edition of Framework Design Guidelines. This second edition is planned to be published around the end of 2008. But you can't afford to wait that long before reading these guidelines, seriously!

DO buy this book for your team or yourself.

Cover of Framework Design Guidelines

- .NET General, Books - No comments / No trackbacks - §

The code samples on my weblog are colorized using javascript, but you disabled javascript (for my website) on your browser. If you're interested in viewing the posted code snippets in color, please enable javascript.

No comments: