1 public sealed class Environment { private Environment() { } public bool HasShutDownStarted public...

1

public sealed class Environmentpublic sealed class Environment{{ private Environment() { } private Environment() { }

public bool HasShutDownStartedpublic bool HasShutDownStarted {{ get { ... }get { ... } }}}}

Best Practices In Framework DesignBest Practices In Framework DesignJelle Druyts – CompuwareJelle Druyts – Compuware

What's wrong with this code?What's wrong with this code?

Best Practices InBest Practices InFramework DesignFramework Design

The Art Of Building A Reusable Class LibraryThe Art Of Building A Reusable Class Library

Jelle DruytsJelle DruytsCompuware .NET ConsultantCompuware .NET Consultant

http://jelle.druyts.nethttp://jelle.druyts.net

3

Your SpeakerYour Speaker

Jelle DruytsJelle Druyts

.NET ConsultantCompuware Professional Services

Framework Design & DevelopmentTechnical ArchitectMentor & TrainerTeam System Focus Group

Microsoft Consultancy ServicesFramework Design & DevelopmentWeFly247

CommunityBlog http://jelle.druyts.netMSDN Articles http://www.msdn.beVisual Studio User Group http://www.visug.be

4



5



It's an uncallable property!

6

GoalsGoals

Is your APIUsable?Reusable?Versionable?

You willUnderstand that API design mattersRecognize good API designLearn the API design process

7

Four Keys Of Framework DesignFour Keys Of Framework Design

The Power Of SamenessFramework Design MattersTools For CommunicationThe Pit Of Success

8

The Power Of SamenessThe Power Of Sameness

9Oh... down to lock!


10

So that's what that "key" thingy is for...


11

(Well, actually, some people could use a refresher on that signal lever...)


12

General PrincipleGeneral Principle

All cars work basically the same wayYou don't read the Owner's Manual

Why should software be any different?You don't read Windows "Help and Support"

Framework usage should be obviousAcross different parts of your APIBetween different versions of your API


13

Naming Conventions QuizNaming Conventions Quiz

Compile this in your head:

A: Compiler errorB: Class declaration C: Variable declarationD: Other

Now mentally compile this:

address Home;

Address home;


14

Naming ConventionsNaming Conventions

All types and publicly exposed members: PascalCasingParameters: camelCasingDon't use Hungarian notation

public class CMemberDoc{ public int CompareTo(object objValue); public string lpstrName { get; }}

public class MemberDoc{ public int CompareTo(object value); public string Name { get; }}


15

Prefixes & SuffixesPrefixes & Suffixes

Compile this:

Follow the patternInterfaces start with 'I'Exceptions end with ...Exception

Same for Attributes, EventArgs, Permissions

IFoo foo = new IFoo();throw new PrinterProblem();

public interface IFormattable {}public class NameAttribute : Attribute {}public class PrinterOnFireException: Exception {}


16

Optimize GloballyOptimize Globally

Prefer global consistency over a local deviation

public class ArgumentNullException : ArgumentException{ public ArgumentNullException () {} public ArgumentNullException (string paramName) {} public ArgumentNullException (string paramName,

string message) {}}

throw new ArgumentNullException ("Must pass an employee name");

// System.ArgumentNullException: Value cannot be null.// Parameter name: Must pass an employee name


17


Meet the developer's expectationsMake consumers of your API feel at home

Be consistentWith yourselfWith the .NET Framework

18

Framework Design MattersFramework Design Matters

19

SimpleSimple

Focus on top scenariosNamespace factoringNamingUse exceptions

A well-designed framework must be...A well-designed framework must be...

new EventLog().WriteEntry("Hello World");

// ArgumentException: Source property was not set// before writing to the event log

20

Explicitly DesignedExplicitly Designed

Create an API specificationReview scenario samplesReview API design


21

Part Of An EcosystemPart Of An Ecosystem

IntelliSenseProperties WindowCLS ComplianceDebugger


[DebuggerTypeProxy(typeof(HashtableDebugView))][DebuggerDisplay("Count = {Count}")]public class Hashtable { ... }

22

IntegratedIntegrated

Use common abstractionsWatch out for common type name conflicts


23

Designed To EvolveDesigned To Evolve

Favor abstract classes over interfacesEasier for versioning (e.g. adding members)

Control extensibilityVirtual members are difficult to version

Test your abstractionsImplement interfacesConsume interfaces


24

ConsistentConsistent

Naming ConsistencyCommon patterns and idioms

AttributesCollectionsAsync PatternDispose Pattern...



25

Framework Design MattersFramework Design Matters

A well-designed framework must beSimpleExplicitly designedPart of an ecosystemIntegratedDesigned to evolveConsistent

...to be able to survive

26

Tools For CommunicationTools For Communication

27

Wouldn't it be great… Wouldn't it be great…

Luckily, there are Tools for CommunicatingLuckily, there are Tools for Communicating

28

Why CommunicateWhy Communicate

Focus on developer, not yourselfYour developers can't read your mindDocumentation alone is not enough

Will this operation block?Will this operation block?

How do I customize this type?How do I customize this type?

How should I use this class?How should I use this class?


29

You Leave ArtifactsYou Leave Artifacts

Framework Framework Design Artifacts:Design Artifacts:

NamespacesNamespaces

TypesTypes

MethodsMethods

PropertiesProperties

EventsEvents

FieldsFields

ConstructorsConstructors

......


30

NamespacesNamespaces

Organizational principle to allow consumers to

Find relevant functionality quicklyExclude less relevant functionality

Not about implementation issues Security, identity, size, performance

Guideline: 1-to-1 link with assembly nameNot required though


31

ClassesClasses

A conceptual model for a thing which can hold state, perform actions, ...Common API design problems

Grab bag types (lack of cohesion)System.Runtime.InteropServices.Marshal

Modeling overly abstractStreamReader vs. File


32

ExceptionsExceptions

Encapsulation of error details used in a structured exception handling systemThrown when code fails to perform what it was written to doCommon API design problems

Using error codes rather than exceptionsDefining far too many exceptionsExposing privacy related information (e.g. file paths)


33

EnumsEnums

Container for named constantsSingular for regular enums

BorderStyle.Fixed3D

Plural for combinable "Flags"AnchorStyles.Left | AnchorStyles.Right

Common API design problemsNot specifying the enum valuesUsing "magic" constants insteadAdding "Enum" to the name

Contrary to Exception, Attribute, EventArgs, ...


34

ConstructorsConstructors

Facility to capture state for an instance at time of instantiation Common API design problem

Doing too much work in the constructorBe lazy, only capture state

public class XmlFile{ private string data; public XmlFile(string fileName) { this.data = DownloadData(fileName); }}


35

MethodsMethods

Expose actions or operationsCommon API design problem

Using properties where methods should be used


36

PropertiesProperties

Logical backing fields that encapsulate access to stateProperty getters

Should be simple and unlikely to throw exceptionsUse read only properties where appropriate

Property settersSetting one should not affect other propertiesShould be settable in any order

Common API design problemProperty vs. Method confusion


37

Properties vs. MethodsProperties vs. Methods

Use a Property ifThe member is a logical attribute

Use a Method ifThe operation is a conversion, such as ToString()The getter has an observable side effectThe order of execution is importantThe method might not return immediatelyThe member returns an array


38

FieldsFields

Represent variables associated with an object or classUseful for exposing implementation details, thereby constraining your ability to evolve the frameworkIn other words

Never expose fieldsAlways use properties


public class XmlFile{ private string data; public string Data { get { return data; } }}public class XmlFile

{ public string Data;}

39

Events Events

Used to inform a subscriber that something happenedAlways follow the Event Pattern

Naming guidelines for Delegate, Event, EventArgs, the method that raises the event, ...

Common API design problemsUsing bad terminology: raised, not fired or triggeredNot using verbs, e.g.: Click, Paint, DrawItemNot using strongly typed EventArgs


40

Generics (.NET 2.0)Generics (.NET 2.0)

Perform the same functionality for a variety of data types

Generic types are substituted at runtime

Use descriptive names prefixed with TUnless a single letter is self-explanatory

Common API design problemsMisusing generics by casting back to e.g. object or to an interface

Use constraints on generic type parameter


public class Comparer<T> where T : IComparable

public class Dictionary<TKey, TValue>

41


Developers can't read your mindDocumentation alone is not enoughYou communicate by leaving artifacts

Different artifacts have different meanings

Follow the guidelines and patterns

42

The Pit Of SuccessThe Pit Of Success

43


In stark contrast to a summit, a peak, In stark contrast to a summit, a peak, or a journey across a desert to or a journey across a desert to find find

victory through many trialsvictory through many trials and and surprises, we want our customers surprises, we want our customers

to to simply fall into winning practicessimply fall into winning practices by using our platform and by using our platform and

frameworks. To the extent that frameworks. To the extent that if if we make it easy to get into trouble, we make it easy to get into trouble,

we failwe fail..- Rico Mariani- Rico Mariani

44

How do I How do I read all read all the lines the lines from a from a file?file?

How do I How do I read all read all the lines the lines from a from a file?file?

45

Visual Studio 2003 EraVisual Studio 2003 Era

“IO” seems like a

reasonable place to start

“IO” seems like a

reasonable place to start

46

Why did they make it

inaccessible

Backup, and try again…

Why did they make it

inaccessible

Backup, and try again…

47

Open.. Looks like a good first step…

Open.. Looks like a good first step…

48

Hmm… OK, what do I do with a FileStream

?

Hmm… OK, what do I do with a FileStream

?

49

Ok good, synchronous

and asynchronous operations.. What the heck is that?

Ok good, synchronous

and asynchronous operations.. What the heck is that?

50

I think I am in the wrong place..

I think I am in the wrong place..

51

Back up, let’s try a different typeBack up, let’s try a different type

52

Ahh, ReadLine(), this looks

more promising..

Ahh, ReadLine(), this looks

more promising..

53

OK, how do you find the end?

OK, how do you find the end?

54

Thanks goodness

there was a sample

Thanks goodness

there was a sample

55

The Pit Of Success WayThe Pit Of Success Way

Developers fall into doing things the right way

56

Just what I need…

Just what I need…

Visual Studio 2005 EraVisual Studio 2005 Era

57

Ah, a string[] I know

just what to do with that…

Ah, a string[] I know

just what to do with that…

58

How simple!How

simple!

59


Make the simple things simple and the hard things possibleAvoid leading consumers down the wrong path

Guide them into just "doing the right thing"

Add value by subtracting featuresAdding features can remove value!

Don't over-designSimple contracts are usually better

60

Key PointsKey Points

The Power Of SamenessMeet the developer's expectations

Framework Design MattersCarefully design an API so it can survive

Tools For CommunicationDifferent artifacts have different meanings

The Pit Of SuccessDevelopers fall into doing the right thing

61

Framework Design Guidelines:Conventions, Idioms, and Patterns for Reusable .NET LibrariesBrad Abrams' Blog:

http://blogs.msdn.com/brada

Krzysztof Cwalina's Blog:http://blogs.msdn.com/kcwalina

FxCophttp://www.gotdotnet.com/team/fxcop/

Microsoft Visual Studio Team Systemhttp://msdn.microsoft.com/vstudio/teamsystem/

Compuware DevPartnerhttp://www.compuware.com/products/devpartner/

62

Thank You!Thank You!

Thanks for your attention

I'll be happy to answer all your questions

Right after the sessionCompuware BoothCommunity Booth: Ask-The-Experts VISUG Booth

1 public sealed class Environment { private Environment() { } public bool HasShutDownStarted public...

Documents

Transcript of 1 public sealed class Environment { private Environment() { } public bool HasShutDownStarted public...