Framework Design Guidelines Digest v2

Almost 4 years ago, I blogged about Framework Design Guidelines Digest. At that time, my blog engine did not support attaching files and I did not have a convenient online storage to put the document on, and so I asked people to email me if they want an offline copy.

Believe it or not, I still receive 1-2 emails a week with requests for the offline copy. Now that I have a convenient way to put the document online, and the fact that I wanted to make some small updates, I would like to repost the digest. The abstract is below and the full document can be downloaded here.

This document is a distillation and a simplification of the most basic guidelines described in detail in a book titled Framework Design Guidelines by Krzysztof Cwalina and Brad Abrams. Framework Design 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 several versions of the .NET Framework.

Comments

• Anonymous
  April 09, 2008
  Extremely useful Krzysztof - many thanks for posting this. Any news on the 2nd Ed. of the FDG book (i.e. the one with coverage of C# 3 and LINQ)? Are you and Brad hoping to get this out in 2008? Kind regards, tom

• Anonymous
  April 10, 2008
  Thanks for this. I had never seen your original post on the digest, but having this in PDF format is great. I am working on getting my manager to buy a couple of copies of the FDG for the office, but in the meantime, I can distribute this to let people get a feel for the kinds of things they should be paying attention to. Not to say that I agree with everything :) "Do prefer classes over interfaces", "Avoid public nested types", and "Avoid out and ref parameters", for example, may have good reasoning behind them, but there are far too many exceptions and caveats for these to be considered as general design guidelines. I understand that the FDG book goes into more detail and gives more explanation, but at the end of the day, you are standing on the recommendation as stated, and these are just TOO general to be useful in real-world design scenarios. I also advise against "Create-Set-Call" when the object has required dependencies. The whole point of constructors is that they serve as a discoverable way for the user to know what dependencies the object needs before it can be used. By using Create-Set-Call instead of constructors, you make the object less discoverable and therefore less usable. There is little that is more frustrating than creating an object with a default constructor, and then getting a runtime exception when I try to use it, telling me that a required property hasn't been set. Unless you count setting that property, and getting another runtime exception telling me that a different required property hasn't been set. If they are required, why aren't they in the constructor? That said though, the majority of the guidelines are good stuff, and I appreciate having this distilled form for general use.

• Anonymous
  April 10, 2008
  Great job! Thanks! Can you provide the rationale behind the "DO use the most derived type for return values and the least derived type for input parameters. For example take IEnumerable as an input parameter but return Collection<string> as the return type"? What would you take for a return value of an interface method? From my perspective, it's more like an input parameter, since an interface will be injected into some framework. Thus it should use most generic types.

• Anonymous
  April 13, 2008
  Krzysztof,  Thank you very much for your book as it literally changed my outlook on programming.  I do have a few questions on some blind spot we have observed while designing frameworks.  

1. The first clarification has to do with the idea of using IEnumerable for parameters.  I understand this and it has served us well for action oriented method parameters however we think this might be questionable for parameters of constructors.  Our reasoning is that constructors are simply a shortcut to a property and we would not use IEnumerable as the property type.  There seems to be some user implied symmetry between the constructor parameter and the property.  I think users would feel strange if they passing in a collection into a constructor and then later added some items to the collection and not have it take effect in the class they passed it into.  If we used IEnumerable we would need to loop through the class and populate the collection property which might cause the users to make some mistakes.
2. In your videos and I believe in the book there are some guidelines in structure usage.  One of the guidelines has to do with size and you specify 16 bytes as a suggested upper boundary.  Is it truly a bad thing to go over that and how far over could we go before it really causes performance issues?  In addition we have a number of classes which its members add up to well over 16 bytes but are immutable, I mean the entire class is immutable.  Can or should I always model immutable things as structures?
3. I really enjoy using the EventArgs patterns with events as it allows us to extent our events in the future as users change their requirements.  My only gripe is that we model many things off of inheritance and have a number of very important methods that we see as being places where change is highly likely in the future.  Is there a pattern similar to the EventArgs that is recommended for these places?  I am especially afraid for methods that are protected abstract in our public API on classes we fully intend and encourage users to create derived classes from.  I just know in my gut that we will need to expand the parameters used by that API.  Is there a nifty tactic to use here?
4. In your book you mention that well designed frameworks are something to be proud of and I think that our company has done a great job in ours.  You mention to let you know when a good one comes about.  We would love to get your input on our public API and how we have gone about implementing the knowledge from your videos and book.  Out API is designed for .net GIS developers and one of the leaders in the field.  We are also Microsoft Gold Partners.  We would love your feedback, do you take these types of requests on through Microsoft and or through outside consulting.  Either way I would really enjoy getting your feedback, good or bad! Thank you very. David Rehagen

• Anonymous
  April 13, 2008
  Sergey Shishkin, Question: Can you provide the rationale behind the "DO use the most derived type for return values and the leastderived type for input parameters. For example take IEnumerable as an input parameter but return Collection<string> as thereturn type"? My 2 cent opinion: I believe that the rational for using the most derived type and specifically IEnumerable for input parameters as opposed to output parameters has to do with knowledge of the operations to perform on the class.  For example if I design a class and write a method that I am 100% sure I will only need to loop through using a foreach statement then I am sure that all I need is IEnumerable.  This makes is very convenient to the developer using my API as he most likely doesn’t need to consider and conversion code to make his data store match mine.  In contrast as a return type from a framework I have no idea how the user will use the “collection” of information I return.  In this case we need a least common denominator kind of class like the Collection.  It has a good mixtures of useful and easy to use methods to manipulate the data.  Imagine all return types being IEnumerable, there is like only one method exposed. :-) Thanks, David Rehagen

• Anonymous
  April 14, 2008
  David, I don't question the IEnumerable as in input parameter. I put the Collectioin<string> as a return type of an abstract member (interface or abstract class member) under a question. My reasoning is that return values of abstractions are input parameter for the framework where thay are defined, and therefore should be least concrete.

• Anonymous
  April 16, 2008
  Thanks for posting this. It is much lighter than the hardcover edition for carrying to code reviews. I found two typos in my copy: Page 7 - Do use EventHandler<T> Instead of angle brackets, I see Spanish punctuation. Page 8 - Do be consistent ... The third sentence starts "The Make sure ...". I think that should be "Make sure ...". Regards.

• Anonymous
  May 09, 2008
  How do I go about designing API for my Library? Gosh where do I start? If you are asking these questions,

• Anonymous
  May 27, 2008
  Great job on the guidelines. While you deserve some credit for distilling a lot into a small set of concise guidelines, I think it would be great to make this set of guidelines into a wiki so that others could add to it and discussions could be saved that amplified on individual guidelines. Would you consider opening up your guidelines to a wiki? You could have a page on each guideline and the overall table of contents would be the list of guidelines. Just a suggestion. Thanks!

• Anonymous
  May 30, 2008
  Krzysztof, I know that a new edition of your and Brad Abrams' Framework Design Guidelines book is scheduled for February 2009 release on Addison-Wesley. In fact I already pre-ordered it on Amazon. Nowadays, many people / publishers provide some kind of online access to yet-to-be-published books. It allows readers to get familiar with new books, and, I believe, an interaction with readers helps authors to polish books and to attract potential buyers too. Do you have any plans to do it with your new book? Any forums, pre-release versions to discuss, etc.? As .NET newbie, I'm looking forward to read your book.

• Anonymous
  June 10, 2008
  These guidelines have been suggested by our developers. We hope they are helpful to you as well. .NET

• Anonymous
  June 11, 2008
  I am planning (and already started) to post sections of the second edition to my blog. The book will be printed on accelerated schedule, so I am not sure I will have time to make the final manuscript available. But, I would love to do it. I will talk to the publisher about it doing it if time permits. Thanks for the suggestion.

• Anonymous
  July 08, 2008
  Acabo de descargar la documentación de una libreria de acceso a datos. Ustedes dirán, &quot;recien documentandose