Framework Design Guidelines Second Edition

I have just finished reading Framework Design Guidelines Second Edition and must say that I enjoyed the read. The first edition of this book was good enough to find a place on my shelf at the office and the second edition expands and improves upon the first. The many annotations dispersed throughout the book by various experts provide some interesting insight into the challenges they have faced. Best practice is not something that is immediately apparent, and often comes from having made mistakes and seeing how things pan out in the real world. It is very refreshing to see people like Brad Abrams and Krzysztof Cwalina drawing attention to the mistakes they made in designing the .NET Framework in order to help others avoid similar issues.

Brad Abrams: We added a set of controls to ASP.NET late in the ship cycle for V1.0 of the .NET Framework that rendered for mobile devices. Because these controls came from a team in a different division, our immediate reaction was to put them in a different namespace (System.Web.MobileControls). Then, after a couple of reorganizations and .NET Framework versions, we realized a better engineering trade-off was to fold that functionality into the existing controls in System.Web.Controls. In retrospect, we let internal organizational differences affect the public exposure of the APIs, and we came to regret that later. Avoid this type of mistake in your designs.

You can now see in the documentation that every type in the System.Web.UI.MobileControls namespace has been marked as obsolete. Working on a large product with a substantial investment in the underlying framework I can certainly appreciate that you will make mistakes despite your best efforts. Creating guidance that reflects what you have learned from past issues is a great way of limiting the accumulation of future technical debt. When the code you write represents a public API you need to very carefully consider each of your decisions. I too have a laundry list of things that I wish had been done differently, and I think anyone who has worked on a product or framework of a substantial size would as well. It is important to not just dismiss your mistakes, but to highlight them along with a means of avoiding in them in the future, and make sure they everyone on your team can learn from them.