Over a million developers have joined DZone.

.NET Fireside Chats - Brad Abrams and Krzysztof Cwalina

· Integration Zone

Learn how API management supports better integration in Achieving Enterprise Agility with Microservices and API Management, brought to you in partnership with 3scale

DZone recently had an opportunity to sit down with Brad Abrams and Krzysztof Cwalina, authors of 'Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition'  In this interview, they discuss some best practices for developers to follow when designing and exposing their own frameworks.

DZone has also made available an excerpt of chapter 9 from Brad and Krzysztof's book, which can be downloaded here.

DZone - Tell us a little about what you do at Microsoft?
Brad Abrams - I am a product unit manager for parts of the .NET Framework in particular the Line-of-business story for Silverlight as well as the Managed Extensibility Framework.    But I am not sure that tells you what I do…  I create joy for developers using the .NET Framework.. I relish identifying the emerging demands in software development and creating frameworks that makes developers lives easier!
Krzysztof Cwalina - I am Program Manager on the .NET Framework team. I lead a team responsible for the general Framework design and architecture, and some APIs in the base libraries.

DZone - What motivated you to write the first edition of this book?
Brad - Krys and I have been working on these guidelines sense nearly the first day development of the what would later become the .NET Framework.   I was designing parts of the Base Class Library such as String and Object.    In doing so I realized that for developers to really have joy while using our framework, we needed consistency across the framework, so ASP.NET, WinForms, ADO.NET all needed to follow the same style and naming conventions.  So Krys and I began working on these guidelines as an internal specification.  We had some success at that, but I never considered doing a book.   A few years later, after .NET Framework 1.0 shipped I had a chance to go meet with several companies and spend one week at a time with several development teams in their work place.  I was amazed that so many of the issues they were debating and struggling with were already covered in the internal document we had been working on.  When I came home, we quickly started working on polishing the specification up into book format. 
Krys - When I started designing APIs for the .NET Framework I searched for available resources on the subject of API design. There were close to none. There were some very good API designers at Microsoft who knew how to do design great APIs, but the knowledge was distributed and not easily accessible. I thought it would be great to gather the knowledge in one document, and make it available to everybody in a form of a book.
 
DZone - Why did a second edition become necessary?
Brad - There were a couple of forces pushing on the need for a 2nd edition.  The most important one was new innovations in the .NET Framework created new patterns and options for .NET developers.   We believed that new frameworks should certainly start to follow those new patterns.  Innovations such as Linq fall into that category.   The other force was that the software development industry continues to mature – new patterns are becoming mainstream that affect the way frameworks are designed.  Patterns such as Test-driven development fall into that category.
Krys - Since the release of the first edition, we learnt how to explain some API design concepts better, so in addition to the changes resulting from new additions of the platform, some sections and chapters were updated to provide clearer guidance. 

DZone - What constitutes a 'Framework'?
Brad -  I think of a framework as being a set of code that is explicitly designed for use by someone else who is often separated by time or space.  If you are just writing some code for yourself to use right away, you can keep a lot of things in your head about the intended usage.  However if you are writing some code that someone else will have to consume, maybe someone you have never meet, maybe someone that can’t practically speaking talk to you, the only way you have to communicate with them is via the design of the framework.
Krys - I am just going to quote directly from the book: framework is a large object-oriented reusable library. I know some people say that framework call user code and user code calls libraries, but I think the distinction is not interesting anymore, as there are not many reusable libraries that do not call back to user code.

DZone - What are some of the hardest problems that developers are trying to solve when it comes to designing frameworks?
Brad - Communication.  Framework designers have some intended usage pattern, some scenarios for how their framework can best be used. Communicating that to the consumers of the framework is really hard.  Documentation is very one dimensional, samples and quick starts show only one narrow path through, there are millions of combinations you miss.  Having direct one-on-one chats is the best way to communicate this sort of thing, but it clearly doesn’t scale.  By using the standard set of patterns that both the product and consumer understand, the communication channel can be greatly streamlined.  The FDG attempts to connincalize these patterns. 
Krys - Getting designs that are both simple and powerful. You can accomplish this with proper layers of abstraction, but it’s hard. It requires a combination of experience, passion, prototyping, modeling, and getting continuous feedback from customers who will end up using these APIs.

DZone - How did you compile these guidelines? Past experiences, Microsoft practices, industry standards?
Brad - There is a wide variety of sources.  Krys and I get lots of comments on our blogs we talked to customers directly about what works and what doesn’t.  Nearly every day some framework designer at Microsoft contacts us with a new suggestion or new problem that spurs a suggestion.  I’d say very few if any of these guidelines are my original thoughts.   Early in the process the single biggest contributor to the guidelines, in fact the person that set the tone for the overall philosophy was Anders Hejlsberg who was also the lead designer for the C# language.  
Krys - My team conducts API reviews of all APIs that we ship in the .NET Framework and many shipped by other teams at Microsoft. The review process is a gold mine for hard API design problems and potential solutions. If a design issue (like when to use classes and when interfaces) is discussed more than a couple of times at a review, I put in on a list of candidates to write a guideline about.

DZone - How have new .NET Framework 3.x features impacted your view of design best practices?
Krys - The core principles and the overall philosophy of how we design frameworks have not changed much. Some details have changed as a result of advances in the base class libraries. For example, LINQ had a relatively significant impact on how we are designing APIs manipulating sets of data.

DZone - Do you think a lot of the developers on the .NET Framework team have this book on their stack?
Brad - Oh quite a few of them do, but then many of the come by my office to borrow my copy or more often just use me as a human version of the book ;-).   Krys also teaches a class regularly at to Microsoft engineers that is very well received… the book is certainly well known on the .NET Framework team..   But I have still yet to hear chapter-and-verse quoted in a design meeting.. I’d love to hear that! 
Krys - Yeah, many of them do and they often us it; like in “Hey Krzysztof, your proposed design is stupid. Go check your book.” :-)
 
DZone - Are these guidelines specific to .NET developers, or do they cross language barriers?
Brad - Well, we certainly focused on the .NET environment, so it is very easy to see how it applies to all the .NET Languages.  But we have actually heard from many java developers that the design principles are the same and I know it I used in some Java shops!   So I think the guidelines are more universal, though all the examples are in my favorite programming language: C#!  
Krys - I would say half of the book’s content is pretty universal. The other half is specific to .NET, but only a very small percentage is language specific.

DZone - Are there any interesting case studies that you can discuss? Have you implemented a recent project using these guidelines?
Krys - Yes, my team works on a new .NET Framework 4.0 feature called Managed Extensibility Framework. The feature is not done yet, but I think it’s a pretty good example of what APIs designed with the guidelines in mind look like. The APIs are well factored, easy to use in common scenarios and powerful enough to support advanced scenarios. Similarly there are new concurrency related APIs being added to the Framework in the next version and I know the team concurrency team is big on the guidelines.

DZone - Who should buy your book?
Brad - You should buy this book only if you want to be a better developer.  If you are designing frameworks, this book will help you know what to avoid and what patterns to follow.  If you are building applications this book will help you understand what philosophy governs how the frameworks are built… it will also help you quickly spot bad, or poorly designed frameworks so you can fix or stay away from them! 

DZone - Do you have any future books in the works? A third edition?
Brad - Oh my… well, like my wife said just after our son was born: “Now is not a good time to ask me that!” 
Krys - Nothing in the works and no plans for now. Writing a book while holding a full time job is really though. The satisfaction from seeing your book in print, especially when it comes out successful, is huge, but none the less too many long nights to do it often.

Unleash the power of your APIs with future-proof API management - Create your account and start your free trial today, brought to you in partnership with 3scale.

Topics:

Opinions expressed by DZone contributors are their own.

The best of DZone straight to your inbox.

SEE AN EXAMPLE
Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.
Subscribe

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}