Framework Design Guidelines For Brussels Users Group

10 Years of Framework Design Guidelines
 Brad Abrams
Product Unit Manager
Microsoft Corporationhttp://blogs.msdn.com/brada
Twitter: @brada

Happy 10 Year Birthday

JoyeuxAnniversaire

Proficiat met je verjaardag

Member Design

10 years ago….

Communicate via leaving artifacts
Framework Design Artifacts:

Properties
Methods
Events
Constructors

Constructors are
lazy
public XmlFile(string filename) {this.filename = filename; }
public class XmlFile { string filename; Stream data; public XmlFile(string filename) { this.data = DownloadData(filename);
}
}
Do minimal work in the constructor
Be Lazy!
Only capture the parameters
9

Properties
public class ArrayList { public int Count {get;}}
Property getters should be simple and therefore unlikely to throw exceptions
Properties should not have dependencies on each other
Setting one property should not affect other properties
Properties should be settable in any order

Properties versus Methods
Use a Property:
If the member logical attribute of the type
Use a method:
If the operation is a conversion,such as ToString()
If the getter has an observableside effect
If order of execution is important
If the method might not return immediately
If the member returns an array

Properties and returning arrays
public Employee[] All {get{}}
public Employee[] GetAll() {}
Calling Code
EmployeeList l = FillList();
for (int i = 0; i < l.Length; i++){
if (l.All[i] == x){...}
}
if (l.GetAll()[i]== x) {...}
Moral: Use method if the operation is expensive

Today…

Extension Methods
namespace MyCompany.StringManipulation {
public static class StringExtensions{
public static bool IsNullOrEmpty(this string s){ return String.IsNullOrEmpty(s);
}
}
}
…
using MyCompany.StringManipulation;
string message= “hello world”;
if(message.IsNullOrEmpty()){
Console.WriteLine(“EMPTY”);
}

Extension methods marry the usability offered by object-oriented APIs with the flexibility of functional APIs.

CONSIDER using extension methods to "add" methods to interfaces
public interface IFoo{
void Bar(string x, bool y);
void Bar(string x);
}
public static class IFooExtensions{
public static void Bar(this IFoo foo, string x){
foo.Bar(x,false);
}
}
…
IFoo foo = …;
foo.Bar(“Hi!”);

CONSIDER using extension methods to manage dependencies
Uri uri = “ftp://some.ftp.uri”.ToUri();
// higher level assembly (not mscorlib)
namespace System.Net {
public static class StringExtensions{
public static Uri ToUri(this string s){ … }
}
}

AVOID frivolously defining extension methods, especially on types you don’t own
Might add clutter
Choose namespaces for sponsor types carefully
Remember that not all languages support extension methods
Users will have to use static method call syntax

AVOID defining extension methods on System.Object
// C# declaration of the extension method
public static class SomeExtensions{
static void SomeMethod(this object o){…}
}

‘ VB will try to find the method at runtime
‘ … but extension methods are resolved at
‘ compile time.
Dim o As Object = …
o.SomeMethod() ‘ THIS WILL THROW
‘ VB users will have to call the method using the regular static method call syntax.
SomeExtensions.SomeMethod(o)

Type Design

10 years ago….

Framework Design Theater
The Main Character:
Bright young developer
The Setting:
Her first big project
The Setup:
Create a class that models a car
Actions required: Start and Drive

Design Pass One: Meets Requirements
Pass one: meets requirements

Design Pass Two: More than Enough

Design Pass Three: Way too much
25

Time to Ship…
Time to cut…

What we ship: Too much and not enough…
27

V.Next: Worse Yet
Now we want to add Color and Model, and we know exactly how
But it is much harder because the design is half done and mostly wrong

The moral
Do as little as possible now (but no less) to ensure room for extensibility in the future

Abstract and Base classes
Prefer broad, shallow hierarchies
Less than or equal to 2 additional levels – Rough rule!
Contracts and responsibilities are difficult to maintain and explain in deep complex hierarchies
Consider making base classes not constructible (that is, use abstract classes)
Make it clear what the class is for
Provide a protected constructor for subclasses to call
System.Exception should not have had a public constructor

Virtual Method Example
public class TheBase : Object {
public override string ToString() {
return “Hello from the Base";
}
}
public class Derived : TheBase {
public override string ToString() {
return “Hello from Derived";
}
}

Virtual Methods
What is printed out?
Derived d = new Derived();Console.WriteLine (d.ToString());
TheBase tb = d;Console.WriteLine (tb.ToString());
Object o = tb;Console.WriteLine (o.ToString());

Virtual Methods
They all output “Hello from Derived”. Why?
Method call virtualizes at runtime
The static type doesn’t matter
This is the danger and power of virtual methods
Danger: Owner of base classes cannot control what subclasses do
Power: Base class does not have to change as new subclasses are created

Overriding: Follow the Contract
Don’t change the semantics of member
Follow the contract defined on the base class
All Virtual members should define a contract
Don’t require clients to have knowledge of your overriding
Should you call the base?

Virtual and non-virtual
Use non-virtual members unless you have specifically designed for specialization
Have a concrete scenario in mind
Write the code!
Follow the Liskov Substitution Principle
References to base types must work with derived types without knowing the difference
Must continue to call in the sameorder and frequency
Cannot increase or decrease range of inputs or output
Barbara Liskov

Interface Usage
public interface IComparable { int CompareTo(object obj);}
No common implementation (the ActiveX problem)
Challenging to version over releases
The smaller, more focused the interface the better
1-2 members are best
But interfaces can be defined in terms of other simpler interfaces

The great proof of madness is the disproportion of one's designs to one's means.Napoleon Bonaparte

Today…

Type Dependency Management
Careful dependency management is the necessary ingredient to successful evolution of frameworks. Without it, frameworks quickly deteriorate and are forced out of relevance prematurely.

Framework Layering

DO NOThave upward dependencies
Avoidhorizontal dependencies
WPF
XML



BCL
Reflection

Libraries , Primitives, Abstractions

CONSIDER placing library types higher on the dependency stack
Definition:
Library types are types that are not passed between components
Examples
EventLog, Debug,
Easy to Evolve
Leave old in, add new one
Beware of duplication!

DOkeep primitives policy free (i.e. simple)
Definition:
Primitive types are types that are passed between components and have very restricted extensibility (i.e. no subtype can override any members)
Examples
Int32, String, Uri.
Hard to Evolve
Little need to Evolve
Typically in lower layers

DO NOTcreate abstractions unless you know what you are doing
Definition:
Abstractions are interfaces or classes with unsealed members that are passed between components.
Examples
Stream, IComponent
Hard to Evolve
Unfortunately, pressure to evolve

Trends

10 years ago….

The Secret of Achiving Great Productivty
A Pit!!

The Pit of Success: in stark contrast to a summit, a peak, or a journey across a desert to find victory through many trials and surprises, we want our customers to simply fall into winning practices by using our platform and frameworks. To the extent that we make it easy to get into trouble we fail.- Rico Mariani

Is using your framework correctly like…
Climbing a mountain?
50

Scaling a peak?
51

Running across a desert?
52

Falling into a pit?

Make using your framework as easy as falling into a pit – then you have achived great productivity

Today…

Test Driven Development
Write tests first, design later
Requires reusable APIs to be testable:

Avoid heavy dependencies, consider inversion of control.
Consider designing for dependency injection.

Heavy Dependencies and Testability
// your API
public class Tracer {
MessageQueue mq = new MessageQueue(…);
public void Trace(string message){ mq.Send(message);
}
}
// your customer’s program that is hard to test
Tracer tracer = new Tracer();
public void ProcessOrder(Order order){
tracer.Trace(order.Id);
…
}

Inversion of Control
// your better API
public abstract class TraceListener {
public abstract void Trace(string message);
}
public class Tracer {
TraceListener listener;
public Tracer(TraceListener listener){
this.listener = listener;
}
public void Trace(string message){
listener.Trace(message);
}
}

Dependency Injection
// your customer’s program that is easier to test
Tracer tracer = new Tracer(new FileListener());
…
}

Dependency Injection Containers
// customer’s program that is even easier to test
Tracer tracer = container.Resolve<Tracer>();
…
}
Check outDI Containers (a.k.a. IoC Containers):autofac, Castle Windsor, PicoContainer.NET, Spring.NET, StructureMap, Unity, and others.

Tools

10 years ago….

Read the manual??
When you pick up your rental car….
Push the seat all the way back
Find an NPR station
Find the exit

Oh, down to lock…

How to use a key…

Oh, you push the PRESS button…

Who actually needs this data?

Why you don’t read rental car manuals ???
You know how to drive your car
All cars work basically the same way
Your rental car is a car
Therefore, you can drive your rental car
That is…
The Power of Sameness

Naming Conventions
PascalCasing – Each word starts with an uppercase letter
camelCasing – First word lower case, others uppercase
SCREAMING_CAPS – All upper case with underscores

Naming Conventions
All types and publicly exposed members are PascalCased
Parameters are camelCased
public class MemberDoc
{
public int CompareTo(object value)
public string Name { get;}
}

Hungarian Notation
Do not use Hungarian notation in publicly exposed APIs and parameter names
public class CMyClass { int CompareTo (object objValue) {..} string lpstrName {get;} int iValue {get;}
}

On Abbreviations, acronym, initialism and the like…
Avoid them!
They are a classic JLT (jargon loaded term)
OK to use them once they become words
Html, Xaml, etc
Don’t just spell them out
Use a meaningful name
Abbreviations of more than 2 letters are cased as words, otherwise ALLUPPER
IO vs. Html

While we are on naming…
Good naming is hard—it takes time
Be meaningful but brief
Use US-English
Colour vs. Color
Principle of least surprise
Look for prior-art
NumberOfElements vs. Count

FxCop – Keeping the "power of sameness"
http://blogs.msdn.com/fxcop

Today…

Framework Design Studio
http://code.msdn.microsoft.com/fds

Dependency Management Tools
http://code.msdn.microsoft.com/fxarch
Define Components
<Group ID=“Component1”>
<Bin Name=“MyCompany.FeatureA.dll”/>
<Bin Name=“MyCompany.FeatureB.dll”/>
</Group>
Define Rules
<Allow From=“Component1" To=“WPF"/>
<Deny To=“XMLDOM”>
Run and Get Output:
From group Component1:
MyCompany.FeatureA.dll should not depend on:
SomeOtherComponent
SomeOtherComponent.dll
Also check out NDepend – a tool for visualizing dependencies.

Summary
10 years of Framework design..
Core Principles of Framework design have stayed the same
There are some significant new advances
Check out the new book!
Brad Abrams
http://blogs.msdn.com/brada
Twitter: @brada

Q&A

© 2008 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries.
The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.

Some images of movie posters sourced from www.imdb.com