Framework Design Guidelines 2nd Edition


My blog was relatively silent for several weeks. First, I was traveling to Europe for the TechEd, then was busy at work, then the holiday break. It’s time to go back to more regular posting.


I will start with an announcement (or at least a more formal and broader announcement): after my TechEd presentation, the first question I got from the audience was whether we are working on a new edition of the Framework Design Guidelines. The answer is “yes”, which I am super excited about. Right before the conference, we signed formal documents with the publisher and started wortking on the book. It’s going to cover the new features in the .NET Framework 3.0, 3.5, and new advances in languages (e.g. LINQ) that are relevant to Framework design. BTW, I would appreciate feedback on what specifically you would like to get covered or clarified.


We are shooting to have the book ready around the end of 2008, but the publisher already sent me a draft of the cover art:


Comments (35)

  1. Keith Patrick says:

    Some things I’d like some clarification on down the line:

    1) where to declare LINQ expressions for best performance vs. readability (make it a readonly so it gets parsed to Expression once or declare it where it’s used so it’s easier to work with)

    2) Naming lambda parameters (examples almost exclusively use x, y, etc., but as they are parameters, is this just due to newness or is naming relaxed when the method is anonymous inline?

    3) Can LINQ (specifically LINQ to Objects) be overused in frameworks? (right now, I go by the "finite loop means use old-style constructs; variable/concurrent loop means LINQ", but what does MS say here?)

    4) Declaring multiple sub-LINQ variables to build a large nested one vs. one variable to store the whole thing (reuse plays into this, as does readability, as does performance…I tend to only declare variables if I reuse the memory, others don’t. With LINQ being potentially used to create very large structures, how does this change?

  2. Jonathan Allen says:

    This is really good news. I am really looking forward to reading it.

  3. Scott says:

    Excellent news!

  4. TraumaPony says:

    Damn it, I just bought the first one!

  5. Krzysztof spilled the beans … We just started working on Volume 2 of the Framework Design Guidelines…

  6. Krzysztof spilled the beans … We just started working on Volume 2 of the Framework Design Guidelines

  7. This is just awesome news. Now, where do we apply for early review copies? 😉

    No. Seriously :-)

  8. Andrew Webb says:

    This is fantastic news!  I can’t wait.  Like Tom K-G, I too volunteer for review duties.  I gave you a decent amount of feedback on the 1st ed, but that was after publication.

    Some specific points:-

    1) I don’t think the title "Framework Design Guidelines" does the book justice.  Your guidelines are *not* just for reusable .NET libraries.  The book should be read by every .NET developer, not just framework designers.  I think of FDG as "Effective .NET".  Is it too late to change the title to reflect/promote its wider appeal?

    2) It would be nice to have some guidance on multi-threading, including: lock attempts that timeout, the volatile keyword, CPU cache lines, the SynchronizationContext class, the CallContext class, and more.

    3) Memory: include guidance on weak references, SafeHandles over finalizers, etc.

    4) Cross-language gotchas, such as VB’s exception filtering code being invoked before the exception-throwing C# code’s finally block has run.

    5) Transactions.  Include guidance on the goodness that’s available in System.Transactions.

    6) And of course I look forward to as much C# 3.0 guidance as you can give.

    Andrew

  9. Mike says:

    I have the first one, I won’t get a second version, but I would consider it if the chapters that deal exclusively with new stuff in .NET 3.0 and 3.5 would be released separately.

  10. Franck Jeannin says:

    Great news, I’m really looking forward to the new edition.

  11. I don’t want to start a naming convention war, but you should define conventions for private members.

    Developers often work on several teams and use tools to validate naming conventions. Having to reconfigure your tools and your mind when you change projects is a pain.

    BTW, I hate prefixing a member just because it’s private.

  12. onovotny says:

    How about some discussion about how tio deal with covariant collections?  I.e., something like

    DoSometingWithItems<T>(IEnumerable<T> stuff) where T : SomeBaseClass

    I’ve seen way too many people assume that they need to specify IEnumerable<SomeBaseClass> as the parameter and run into all sorts of issues with getting collections of derived types to work.  It looks obvious but it’s something that people easily mess up.

  13. onovotny says:

    Also, advice about implementing IEquatable<T> within an inheritance hierarchy would be nice.

    For example, I have IMyInterface, MyClass : IMyInterface and MyDerivedClass : MyClass.

    I want to implement IEquatable on the interface but I want to ensure that EqualityComparer<T>.Default uses the methods even if someone uses MyClass or MyDerivedClass as the type params.  

    Advice on how to implement the interface at each level and dealing with the various Equals overrides would be very helpful.

  14. Chris says:

    Hi Krzysztof, great news.

    Not sure if this is appropriate for the book, but I’d really like to find some ‘canonical’ documentation on use scenarios for LINQ, the ASP.NET Dynamic Data Controls and when to use SQL Metal directly.  Additionally, I’d like to find out the limitations of these code gen approaches and when its best to continue to write code by hand (what are the upper limits of their customizability?).  Also, performance patterns for LINQ — how often should we create instances of data Context objects, can you cache them, creat singletons (gasp), etc

  15. Sean says:

    From the first edition, I loved the comments made by PM’s/Devs on the framework, what they should have done, what could be done better, etc. Make sure that type of thing gets into the new stuff! <g>

  16. Kevin Kerr says:

    I vote for WPF guidelines. With WPF there are 10x as many ways to solve problems than plain .NET. This means there are 10x as many ways to shoot yourself in the foot. How about 10x as many guidelines for the WPF side of things? :)

  17. Jeff Moser says:

    Some best practices on designing libraries that have extension methods would be good.

  18. Kazi says:

    Hi!

    It would be great to see a chapter for Model-View-ViewModel WPF pattern.

    Kazi

  19. Krzysztof Cwalina says:

    Thanks for all the support, comments, and suggestions. Some of the things are already on the list, some are great new suggestions. The topics we want to avoid are all that are not related to API surface area design. We want to keep the book focused and be the definitive source of information on API design; we will never succeed at being the definitive source for information about everything related to .net development. Having said that I am dreaming about writing something like Framework Architectural Guidelines (layering, dependencies, threading, etc.), so maybe one day all of these suggestions will find their way into a Framework guidance book. 

    Mike, I have already made some updates to the manuscript inline (comments and errata items from readers) and clarifications to some existing guidelines, but majority of the new content will be easily identifiable and separated. I don’t think we will have many new chapters, but definitely many new sections in existing chapters and based on your feedback I will add a list of added sections to the front matter. Thanks for the feedback.

    Paulo, naming conventions for private/internal identifiers is something that many people ask. There is an appendix in the book that talks about these. Having said that, I prefer for these to keep being informal as I also don’t want to get into internal team naming wars :-) Public identifiers are a different ball game; they affect productivity of people outside of the internal dev team (and that’s the main focus of the book).

  20. Krzysztof Cwalina says:

    Oh, for those who would like to review the manuscripts, please send me email (kcwalina at microsoft.com) expressing interest and with a premission to forward it to the publisher.

    And Thanks! Feedback from people passionate about API design is invaluable!!!

  21. Krzysztof Cwalina says:

    Also, I just updated the picture of the cover to reflect Anders’s change in the title.

  22. Keith Patrick says:

    Here’s another one (that I’m sure will tick off some folks): less special sections on Visual Basic. Seems like MS always gives VB special attention, even in terms of it being a more "complete" .Net implementor than C#, but in terms of API design, there’s a disproportionally large amount of annotations related to VB in what should be, by and large, a language neutral platform.

  23. Krzysztof and Brad have announced they are working on the second edition of the awesome Framework Design

  24. Krzysztof and Brad have announced they are working on the second edition of the awesome Framework Design

  25. Programming says:

    Krzysztof spilled the beans … We just started working on the 2nd edition&amp;;of the Framework Design

  26. Guidance  for data access to determine when to use LINQ, ADO.NET, Entity Framework, typed DataSets, etc in different scenarios would be useful. Given all of the data access options, even alternet options like SubSonic and nHibernate, it is getting harder to maintain legacy applications that choose all kinds of unexpected approaches. It appears that LINQ data contexts will replace typed DataSets, but a prescribed approach given all of the available options would be very useful over the next several years.

  27. Jens Hofmann says:

    The new Async-Pattern (Event-based Asynchronous Pattern) in the .NET Framework 2.0 used for classes System.Net.WebClient, System.Net.NetworkInformation.Ping, System.ComponentModel.BackgroundWorker etc. (Not BeginnXXX and EndXXX but that XXXAsync, XXXAsyncCancel)

    There are many naming conventions for classes, events and methods in this Pattern.

  28. You know that I&#39;m a big fan of framework and library design so also have been a big fan of Framework

  29. Markus Hjärne says:

    First I would like to thank you (and Brad Adams) for writing this very essential book.

    About the 2nd edition, I would really like to see more guidelines on how to organize your types in a namespace hierarchy and on how to package these same types into different assemblies. Even though the two concepts really are quite unrelated and orthogonal, they often get mistakingly intermingled. So it would be really helpful to have guidelines to help you to think straight when performing these tasks.

  30. chris says:

    I hope you keep the book focused on core parts of the framework and stay away from areas such as WPF, Card Space, silverlight.

  31. These guidelines were just added as part of an update to the Framework Design Guidelines book ( upcomming

  32. Krys and I just finished writing the update to the framework design guidelines and you are can already

  33. D Hill says:

    I just bought early verison at the Rough Cuts http://safari.informit.com/9780321545671

    Looks like a greta outline.  Stick with it.

  34. [ Nacsa Sándor , 2009. január 19. – február 5.] Ez a Team System változat fejlett eszközrendszert kínál

  35. Brian Barnett says:

    Add a chapter or section devoted to service or WCF-related API guidelines.