Dr. Dobb's Journal, April 2006

Framework Design Guidelines

By Peter N. Roth

Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries
Krzysztof Cwalina and Brad Abrams
Pearson Education, 2005
384 pp., $40.00
ISBN 0321246756

.NET 2.0 is the result of six years of work and is actually the third version of the Framework. According to lore, this is how many versions it takes Microsoft to "get it right," so this version of .NET looks like it could be the real deal.

As anyone who has built a framework recognizes, well-designed frameworks are full of trade-offs. Cwalina and Abrams are correct when they say that "prototyping is not implementation." Frameworks need to be designed, which is expensive and hard work. Out of their six-year experience, they offer guidelines of four varieties, each of which begins with one of these verbs: Do, Consider, Avoid, and Do Not. But how to decide how to phrase a guideline? Development of these can be as difficult as writing code and is often subjective and contentious by nature, as they point out early on.

For framework users, the value in learning and conforming to the guides is that the convention enhances your capability as a user to deduce the meaning of other parts of the framework simply by familiarity with the convention. By adhering to the guidelines, the thesis is that in turn, you'll be writing good code, where "good" means "more easily understood by other programmers."

I would say the level of difficulty of the text is medium. In an early draft of this review, I wrote that the text could be life changing, and could be used to settle newsgroup disputes. Clearly those are utopian views, but they are not wrong.

Still, there are a few missing guidelines. For example, I would add:

• Do Not use l (lowercase L), O (uppercase o), or I (uppercase i) as single-character variable names; they're too easily misread as numbers.
• Do use at most one loop per method (but my experience is obviously different from the authors'). This small example also shows that Do and Do Not are somewhat interchangeable, depending on how one states the guide.

There's a ton of additional material available on web sites and blogs, but I found the contents of the enclosed DVD most interesting. One component is visual presentations of the textual material—lectures. Running these requires Microsoft XML Parser 4, which it tries to install. On my machine, this attempt failed with a request for an unnamed disk. So first I downloaded and installed MSXML 6, and the DVD then happily installed version 4 over it. After this install, the visual presentations are available and worth a view: They are the majority of a two-day internal Microsoft training seminar.

A link is provided for you to download FxCop, a tool that reads your code and reports violations of the guidelines of this text. In my Cube(x) function, which returns x³, FxCop suggested I provide a more meaningful name than x. While the tool is worth having, you'll want to tune the rules to your own situation, and ignore some suggestions.

TxRef is a command-line app on the DVD that provides C++ header-like printouts for C# executables. The developers of TxRef also ignored a few guidelines, which gives me the opportunity to offer one final guideline—do as I say, not as I do.

Framework Design Guidelines concludes with a Glossary and a list of Suggested Reading. The glossary will be welcomed by readers new to .NET, patterns, and object-oriented programming. The reading list includes the venerable Psychology of Computer Programming by Gerald Weinberg (1971), still appropriate, and worth reading.

DDJ