PDC Experience 2008: Day 1: Session = "Framework Design Guidelines"

Guidelines started back in 1998.  The talk is based on the book "Framework Design Guidelines"

Communicate via leaving artifacts

1998 Guidelines

Constructors are ...

Do minimal work in the constructor

• Be lazy
• Only capture the parameters

Properties are

• 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 another
• Properties should be settable out of order

Properties vs Methods

Use a property

• If the member logical attribute
• TODO: Finish

Use a method

• Use a method if the operation is expensive
• TODO: Finish

Type Design

• Do as little as possible (but no less) to ensure room for extensibility in the future.

Abstract vs Base classes

• Prefer broad, shallow hierarchies
• Less tan or equal to 2 additional levels - Rough rule!
• Contracts and responsibilities are difficult to maintain and explain in deep complex hierarchies
• Consider making base class not constructible
• Make it clear what the class is for
• Provide a protected constructor for subclasses to call
• System.Exception should not have a constructor
• Overriding : Follow the contract
• Don't change the semantics of member

Virtual and non -virtual

• Use non-virtual members unless you have specially designed for specialization
• Have a concrete scenario
• Write the code!
• Follow the Liskov Substitution principal

Interface Usage

• 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.
• 2008 Guidelines

Extension Methods

Extension methods marry the usability offered by object oriented APIs with the flexibility of a function API

• Consider using extension methods to "add" methods to interfaces.
• Consider using extension methods to manage dependencies.
• Avoid frivolously defining extension methods, especially on types you don't own.
• Might add clutter
• Choose namespaces for sponsor type 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 (this is handled differently by VB.NET

Type Design

Framework Layering

• Do not have upward dependencies in the layer
• Avoid horizontal dependencies

Libraries Primitives and Abstractions

• Consider placing library types higher on the dependency track
• Definition
• Library types are types that are not passed between components
• Examples
• EventLog, Debug
• Easy to Evolve
• Leave old in, add new one
• Do keep primitives policy free (i.e simple)
• Definition
• Primitive types are types that are passed between components and have very restricted extensibility
• Examples
• Int32, String, Uri
• hard to Evolve
• Little need to Evolve
• Do not create abstractions unless you know what you are doing
• Definition
• Abstractions are interfaces of classed with unsealed members that are passed between components
• Examples
• Stream, IComponent
• hard to Evolve
• Unfortunately, pressure to evolve.

Trends in Design Guidelines

Is using your framework correctly like ...

• Climbing a mountain (bad)
• Scaling an icy peak (bad)
• Running across a desert (bad)
• Or a easy a falling into a pit (Good)

Test Driven Development

Write test cases first!

Requires reusable APIs to be testable

• Avoid heavy dependencies, consider inversion of control
• Consider designing for dependency injections

Heavy Dependencies and Testability

• Use Inversion of Control
• Dependency Injection

Naming Conventions

PascalCasing - each word starts with an uppercase letter

camelCasing - First word lower caps

• PascalCase for public methods
• camelCase for private members
• Do not use Hungarian Notation in publicly exposed APIs and parameter names

On abbreviations and acronyms

• Avoid them
• They are classic JLT (jargon loaded term)
• Ok to use them once they become words
• Don't just spell them out
• Use meaningful names
• Abbreviation

While we are on naming...

• Good naming is hard 0 it takes time
• Be meaningful but brief
• use US-English
• Colour vs. Color
• Principal of least surprise
• Look for prior-art
• NumberOfElements vs. Count

Tools

Framework Design Studio: Compares versions of the API

Dependency Management Tool: Checks for dependencies