Jan 20 2010

Interface Phasing

&


On the concept of contracts and contracts, I think we need "interface phasing". Having a phased relationship between two parties.
It is imperative that objects and at a higher level, an Application, can change the way they interact by who or what is accessing them.

 

An object should present itself differently to different audiences. Imagine a developer seeing a specific interface, but not a user, or IDE vs developer. Its not role based, because it could be different per application to application communication, although a similar effect can be achieved.

The concept is simple.

I think that coding today suffers from

  • Repetitive nature of structural elements: for example: creation of large Object Models, classes, properties, collections and so on.

  • Creating Object models with no separation of Context or concerns. I want an object to 'share' code, but for different reasons. Cross-Cutting. Yes, I can create a new object and share code, but that's not always the answer. Imagine two object models, where one is a Facade of the first. I want to simply map the one to the other, not create the entire structure for it again.

  • Different ways of extending components. Different ways of creating add-ins, Custom B2B, Adaptors, Bridge patterns etc. It can all be made easier, if we used a "Global extension object system"

  • The 'under the hood' 'abstractions, keep changing - not for the better or necessarily for the worse, but for no distinct benefit.

  • Contractinitis - Nothing works unless its all explicit. In .NET, can't call the web service with your Person Object, cause its not the same namespace etc.

 

Create automatic and dynamic proxy layers based on metadata and intention of communication. The code is then 'assembled' and made ready for the communication. The code is assembled from existing non contextual code that can fit into a common proxy container and interact.

On a simple level, imagine, you create SOA like methods, stateless and they are formulated by the runtime into a new object that looks like the one required.

This is not the complete answer, but we really need to get to 'smarter relationships' rather than contracts.

See Lack of MetaData on code and .NET Framework libraries

Read Evolution, Architecture, and Metamorphosis - A great piece of work.

 

Tags:

Jan 20 2010

The Concept of Non Contractual interfaces


Our software contract world is the accepted norm, and of course we have come a long way with the philosophy as its been the corner stone of our development languages and platforms for how long.
However, other concepts have also existed. In the seemingly archaic world of top down programming, there were no interface or object-oriented contracts. Instead a form of duck-typing and vtable calls ruled the day or even worse pointers and addresses.
Today the concepts of interface and implementation etc are sometimes lost on the new generation of developers, as its so seamless today.
However, I think that if you look at the real world, communication is lossy, and not defined by the same kind of rules.

In the real world we kind of just make sure there is someone around, or get the person focused on us, then we talk. The receiver understands or does not understand, or does not listen, or hears and acts on all that is said. In the real world, not every communication has "roger", "over and out". There are obvious benefits to having it sometimes, but a real pain in other situations.

The interaction of software frameworks is a real candidate for a more lossy communication, or a Communication Agent, put in software terms. The ability to translate messages from "intention to result" is imperative.

When a call is made to string GetUserName() or string getNameOfUser, the intention is the same, but in our current forms of software architecture, a human would have to use a design pattern, Adaptor, Bridge or whichever suited to accomplish it, when clearly, to our human eyes, the function could well be identical but for name.

A new kind of Interface Definition language is needed to declare intentions of interfaces, and allow a mapping agent to successfully arbitrate a result.

Tags:

Nov 13 2009

.NET vs .NET (a quick performance test)

Category: .NET | Frameworks | Visual StudioJonathan @ 06:51

Since we can target our code to a specific compiler and target the platform of our choice, I thought it would be fun to see what sort of differences in speed, it would bring up.

I did two tests. First I looped through integer values, the columns on the left and then object assignments for the column on the right. For the object assignment, I created a simple class with a string property, created the class and set the property in the loop. Interestingly there were some differences.

The object assignment is obviously a large percentage of what we do in an object oriented world. Visual Studio 2010 was a lot slower than 2008 all round, but did perform decently for .NET 4.0. However small this simple test is it shows quicker times from 2008, and it shows that 2010 suddenly improves when using .NET 4.0. It took around 25 seconds longer to create the objects targeting the .NET Framework 3.5 using VS 2010, than VS 2008.

The test was done in Debug mode, Vista 64.

integer loop
2.0 2008 3.0 2008 3.5 2008
2.7735668 2.7634976 2.7670054
2.7659806 2.7567702 2.771937
2.7700194 2.7612681 2.7782053
2.7697211 2.7606385 2.7811199
2.7750242 2.7747622 2.7802291
13.8543121 13.8169366 13.8784967
2.0 2010 3.0 2010 3.5 2010 4.0 2010
2.7465096 2.7569809 2.7655086 2.734276
2.7577021 2.7531411 2.7583006 2.753255
2.7505392 2.7429336 2.7568989 2.753271
2.741854 2.7503117 2.7655838 2.761961
2.740013 2.7474619 2.7784012 2.759656
13.7366179 13.7508292 13.8246931 13.76242


object creation, string property assignment
2.0 2008 3.0 2008 3.5 2008
15.9305226 15.38386 15.8581671
15.2397368 14.59608 14.7847291
15.1368118 14.7387 14.6265273
14.7425454 15.42782 14.5719368
14.7806622 15.25851 14.9774767
75.8302788 75.40496 74.818837
2.0 2010 3.0 2010 3.5 2010 4.0 2010
20.3244424 20.76454 20.7134072 18.37988
20.2770724 20.61586 20.8497297 18.04806
21.2592798 20.74874 20.856723 18.32123
20.5916017 20.64923 20.897214 18.62922
20.3946783 20.61862 20.7991 18.42922
102.8470746 103.397 104.116174 91.80762

Tags: , ,

Nov 13 2009

Converting an Enterprise Level App from VS 2008 to 2010

Category: .NET | Frameworks | Visual StudioJonathan @ 02:53


The Wizard opened straight away, I clicked next.
After a few popup dialogs, requesting from me things such as Can't find the source control, remove source control binding? and would you like to upgrade the web projects to .NET 4.0?, which I responded yes to all.

The first problem came when the web project tried to bind to IIS, but failed. the wizard asked if I would like to create the virtual folder, I said yes and it failed, since it already existed. Accepting this to be a fair point, I created a new IIS Application, mapped to my project, edited the project file (right click on the project which failed to load) and selected Edit Project file. The edit context menu is a simply but great new useful feature.

I then reloaded the project from the same context menu and it loaded perfectly.

Running the application worked first time. I ran our manual Sanity Test, our automatic unit tests and all passed first time.

In short, upgrading the web app to .NET 4.0 upgraded and ran perfectly well.
but what would it do if I changed the target platform back to 3.5?

I went directly to the project properties and changed the target platform to 3.5, at which point I was informed that a project reload was required.
I then went through all 16 projects in the solution. Some had changed to 3.5, some were still on 4.0. I changed all projects to 2.5, compiled and ran.

The first Error

I got the following error:
"Could not load file or assembly 'xxx' or one of its dependencies. This assembly is built by a runtime newer than the currently loaded runtime and cannot be loaded."

Oops, I missed one.
I changed the version to 3.5, rebuilt. Still error.

What happened was all the projects hooked up to Microsoft.VisualStudio.QualityTools.UnitTestFramework.dll - refused to change to version 2.*. The project reverted back to version 4.0, and I could not keep it in 3.5.
Eventually, after trying tons of manual attempts to reference alternative versions, rebuild etc, nothing worked and I was done.

Start from the top

I decided to start from scratch, get my backup up and start the wizard from scratch, this time, not upgrading to 4.0 from the get-go.

After repeating the exercise and not moving to .NET 4.0, I discovered that all the UnitTestFramework dependent projects had been forced to version 4.0 and I got the same error as before.

You can view the problem on Microsoft Connect, and as I did, discover that not much of a solve has been written there. (Please leave your feedback on the site)

STOP. It is a shame that one would consider the .NET Unit Testing Framework to be such a small piece of the whole 2010 pie, was the reason I cannot upgrade an Enterprise project. Not good for test first is it?

[Let me just point out that Visual Studio .NET 2010 is in Beta 2, at the time of this post]

Tags: , , ,

Sep 11 2009

What is Production Code and how do

Category: .NET | Design | Design Patterns | MethodologyJonathan @ 08:36

... you know when you have it, or not?

You see it written in code samples: No warranty, please take care if you use in production environment. This is not production code, but what does production code really mean?

Firstly production code can be any code that is in use. But that does not refer anything about quality. Just because software is on the shelf, does not mean its good quality.
Production code must have some sort of quality level.

Amusingly the DSDM pocket book, (Atern) says that "it must be good enough" - which makes me laugh, then cry.

Quality is subjective yes, and quality costs money. So what should production code be?

The following is a list of heuristics for referring to code as production code.
  • More than 40% of your application has Unit Tests
  • At least 3 or more people have spent time actively seeking bugs, for longer than 30% of the time it took to originally write.
  • At least 3 or more people have been actively seeking bugs, in at least 5 different configurations/environments.You have mixed the environment (different server, different database name, altered culture/region, etc).
  • Bugs have been solved with SolvingDesign (A lasting solve)
  • Code Regression is reduced, practically to a stand-still. A ratio of 50 bugs solved per 1 reintroduced is a good ratio. 5 bugs solved for 1 reintroduced is a terrible ratio.
  • Users have used the code for at least 40% of the development time taken, reporting bugs, and the system recompiled and redeployed at 5 times during this period. (preferably at intervals, so input can be recalculated)


Influence that will present itself, and cause you into thinking its production code, before its not.
  • Deadline and other pressures
  • Reactionary mindset, rather than pre-emptive
  • Bad company software creation intelligence (what else can you call it?)
  • Human traits, inexperience, carelessness etc


Tags: , ,

Aug 20 2009

An ASP.NET web root link handler

Category: .NET | asp.net | c# | Visual StudioJonathan @ 02:56
In order to get a useful, all purpose, all use client-side href link back to root, from anywhere down the web folder structure, and paying attention to IIS6, IIS7, Cassini and other Visual Studio internal web hosting scenarious and of course the odd bug within ASP.NET and your own web site code, I created a handler for ~/.


Here is the html I wanted.


<a href="~/">Some link to root of site</a>



public class RootHandler : IHttpHandler
    {
        #region IHttpHandler Members

        public bool IsReusable
        {
            get { return true; }
        }

        public void ProcessRequest(HttpContext context)
        {
            context.Response.Clear();
            string toUrl = context.Request.ApplicationPath;
            context.Response.Redirect(toUrl);
            context.Response.End();
        }

        #endregion
    }


    <handlers>
      <remove name="root"/>
      <add name="root" verb="*" path="~/" type="Namespace.RootHandler, Assembly"/>   
    </handlers>


Then with a little more code in the ProcessRequest method, you could find the ~/ part of the url, strip it down and modify the url.


        public void ProcessRequest(HttpContext context)
        {
            context.Response.Clear();
            
            string toUrl = context.Request.ApplicationPath + "/";
            string url = context.Request.RawUrl;

            int idx = url.LastIndexOf("~/");

            url = url.Substring(idx + 2);
            
            url = VirtualPathUtility.Combine(toUrl, url);

            context.Response.Redirect(url);
            context.Response.End();
        }


It is only with .NET Framework 3.5, where HttpHandlers have gotten to an acceptable bug free level for use.

Warning: this is a simplistic example for purpose of this post, please be careful in production scenarios.

Tags: , ,

Jul 23 2009

ASP.NET Framework Should Haves

Category: .NET | c# | Design | Development Tools | Visual Studio | asp.netJonathan @ 05:53

ASP.NET should have been a plug-in from the start. The IIS Handler, should have been split into (.NET with ASP.NET) and (.NET without ASP.NET). The idea of a config file and a WebConfigurationManager is not and should not have been specific to ASP.NET.

One cannot help but feel that ASP.NET was designed with Web Server Controls as the flagship feature. "Create that 3rd party market for web". No real thought paid into how people actually use the web on simple terms.

What I am writing here, probably resembled the paper David Heinemeier Hansson scribbled on when thinking and designing Ruby on Rails, but I have no intention of mapping features, just stating the obvious.

Get Server returns html
Post Server *saves data and returns html
Querystring may change what code is executed, and change the "context"
Url may require changing, remapping, extension changes etc

Now, to do this in ASP.NET is relatively straight forward?
Yes it is, simple enough to do each thing, but it gets more complicated when you want all these ideas together.

There is also a grey area as to what we should call easy. Yes it's easy to do x, but is it simple and will it remain simple as time goes by.
The minute you start asking some questions, ASP.NET starts to give varying levels of success. What if it was posted from a different server? What if the html had to be static and not dynamic? what if you need to create your own physical files and return those to the browser? What if you did not want an aspx page at all? What if your new Module wants to create the Page (HttpHandler)

Asp.NET is far too cluttered, and muddled. The design from, Web Server to a response, should have been completely extensible and pluggable.

The problems that I have come across, over the last few months (again), have all been relating to ASP.NET not being able to let go. ASP.NET has so many tenuous links to what you write, its everything but impossible to break away.

A framework should always be designed in layers. A framework should not be a large foundational block, written to sit at the bottom only.

if I am not entirely clear, perhaps a few links into oddities will help.
Actionless Form
Scenarios where switching viewstate off like this does not actually work.
and why caching problems like this does not work properly all the time.
Double postback scenarios
The ridiculous IsPostBack code and scenarios
and it does not end. Friendly adaptors, bad html to asp.net naming, lack of rudimentary support for url manipulation, deflected posts and more, makes ASP.NET a framework look like this.

In my humble opinion, on design/framework notions here are some ASP.NET should haves.
  • The HttpRuntime and associated server objects should have been better formulated and allow for better involvement. Allow extensibility.
  • The runtime should have made Pages (HttpHandler) an optional unit of packaging and code, not the complete target.
  • Better fine grained Page type. Split it into more pieces, separating cache, viewstate and more from the design. So we can use at any of the levels of interest.
  • HttpHandlers should have been designed as a clear open and extensible list of handlers. The pattern should be more workflow like.
  • The compilation process of asp.net syntax and html should have been an exposed set of objects, also extensible. (build providers)
  • Expressions should have been designed much better, and give us control of more of the syntax.
  • It should have been easy to create an aspx file and not have code behind, and include your own syntactical sugar.
  • Asp.NET should have been a plug-in to the .net engine for the web, and not soo tightly coupled.
  • Classic ASP should have been a continued 'available' and compatible unit within the framework.
  • Should have reduced the gap between Server and Client side code. not server controls writing client code out, but rather a whole new better solution
  • All that time it took to develop usercontrols and pages and server controls, could have been better spent on using existing syntax and an html object model for controls. It would have been compliant, less error prone and significantly better.


Personally, I cannot wait for the rewrite of ASP.NET. Unfortunately with all the man hours, money and face they have put into ASP.NET - they wont be brave to throw it away. Yes folks you will be stuck with it, and its even going to version 4.

I like the .NET framework as a whole, I love the c# language, but ASP.NET is a beast. Why on earth they built MVC on top, I'll never know. If it was not for Visual Studio supporting ASP.NET, it would be a disaster.

ASP.NET just should not have!

Tags: , ,

Jun 23 2009

What I am building now

Category: .NET | c# | FrameworksJonathan @ 06:33

I have to build Forms. Web Forms, digital versions of paper forms. You know the kind. You get probably hate filling them in.
Currently there are a few forms, but expectations are, that many, many more forms are to follow. Forms for Edit, Forms with Permissions (part of forms visible to some, editable by others), forms saved as pdf, as html. Each form can expect largely varying workflows. Data from forms to varying database schemas. A complete nightmare to implement generically, but there is a need for a lot of it to sit on top of something familiar and useful across domains and clients.
Some of the goals include:


- easier to maintain, add forms etc, than previous implementations.
- easier to edit and deploy to different sites.
- customizable workflow
- customizable processing.
- Notifications, manual override of process, some manual flow points.

This is kind of like ruby on rails meets Windows Workflow foundation. But alas that wont work out very well, as a combined technology and WCF is overkill in some areas, and might be worth doing on another level. However this is a .NET team, with no WCF experience. Would a quick Activity based object model not suffice?

I have been sitting with this for a few weeks now, and I have 90% of my plan of attack. However, I have started developing already. You guessed it, I have already built a small Framework of my own that will suit this development.
If you have bright ideas, let me know.

Tags: , , ,

May 22 2009

Lack of MetaData on code and .NET Framework libraries


Although .NET Reflecton offers a decent look at the Types you build, it is pretty generic in its offering. For example, it does not yet provide us with capabilities to control and secure how Reflection can inspect our Types. If you do not want a Type to be Instantiated via Reflection, or if you would like to restrict certain Types from being visible at all. Further there is no idea for extension or change. One cannot simply plug into Reflection and override behaviour.

High abstractions and higher flexibility

Many more wrappers are needed, at a higher level, which would sit on top of .NET Reflection. For example, architectural dependencies. Agile mechanisms, if code had enough metadata attached, one could alter the code via reflection/refactoring in a much more dynamic way. Consider the following two web service methods in two different companies.
  public class PersonService
    {
        public void AddPerson(string lastname, string firstname, 
            string birthdate)
        {
        }
    }

    public class PersonWebService
    {
        public void AddNew(string firstname, string surname)
        {
        }
    }

You can see that they are completely different contracts. Interface and contract speaking they are like apples and sand. However, to your mapping, calculating, schema, metadata, tagging and understanding brain, its the same thing.

What we need, is to remove ourselves from Contracts to something more like guidelines.

  public class PersonService
    {
        [Operation(Schema:Person, "Add")]
        public void AddPerson([schema(LastName)]string lastname, 
             [schema(FirstName)]string firstname, 
             [schema(DateOfBirth)] string birthdate)
        {
        }
    }

    public class PersonWebService
    {
        [Operation(Schema:Person, "Add")]
        public void AddNew([schema(FirstName)]string firstname, 
             [schema(LastName)]string surname)
        {
        }
    }

Tags: , , ,

May 22 2009

Reverse Composite

Category: .NET | c# | Design | Design PatternsJonathan @ 04:19
Not sure if there is a Design Pattern relating to this kind of need in another pattern catalogue, but it seemed simple enough to reverse the GOF composite. A class with a collection of leaves, that iterate, recurse its way up to the root. This needs work in terms of combining or actually making a variation on the composite. I think that this is perhaps only a .1 degree of separation.

Problem

You have a list of Items, that may or may not be related. There may be 1 or more trees. You have a bag of unsorted or related objects as a signle array. You need to maintain a complete list of leaves, but also need the relationship/heirarchy to become apparent. You want to express the heirarchy in a Composite Pattern, but it would exclude certain leaves has it has no part in the particular root that the composite gets built on.

Context


You need a collection of leaves, from across the composite tree. You need to have access to the parent and/or recurse to the root.

Types are stripped from its branches.

 

Structure

A class that works with a collection of leaf classes, that each point to it's parent. In effect a composite in reverse. Keep all the leaf objects in a collection and build the heirarchy from the bottom up.




One of the main reasons behind this is multiple paths to a set endpoint. The root becomes the set endpoint where by we can plot a course from a leaf. The Leaf though is where we start from and full knowledge of all leaves should be known at the outset. 

By adding a Parent on the Composite (GoF), you can achieve a similar result, but you will not have a flat list of leaves.

Tags: , ,

May 13 2009

VS.NET Add-ins worth looking at

Category: .NET | Development Tools | DOTNET | Visual StudioJonathan @ 04:53

Run VS.NET as Administrator on Vista.

Export your settings using Tools | Import and Export Settings, don't let another windows reinstall take it all away from you.

Get Regionerate
- but make sure you use the "Remove All regions" command, before trying to apply others. It wont replace your existing regions.

Get Studio Tools, for File manager and the tear off editor.

Download Dev /efor - not sure about the name, but it works nicely.

Snippet Editor, useful, for changing the way the existing snippets work, as well as new ones.

Carl J has a large list of add-ins.

Tags:

May 1 2009

The Every Project Framework - Part 1

Category: .NET | Design | Design Patterns | Frameworks | MethodologyJonathan @ 07:11

In The Every Project Framework - Introduction, I spoke of structure and infrastructure, lets now move a little deeper.
More...

Tags: , , , ,

Apr 20 2009

Refactoring complex classes using Composition Part 3

Category: .NET | c# | Design | Design PatternsJonathan @ 02:55

To conclude the previous two posts on using composition for refactoring complex classes

Refactoring complex classes using Composition Part 1
and Refactoring complex classes using Composition Part 2

Why should complex classes be refactored? To make code smaller and more manageable. To separate code that changes at different rates, and which are not concerned with the same things.

Composition vs Inheritance? Composition = "has a" relationship, Inheritance "is a" relationship. Inheritance quickly makes you feel like you create Object-Oriented code, but its one of those devices that should be used for a real reason, not just off the cuff.

Reading
- Some background from C2 Wiki - Composition Instead Of Inheritance
- A good principle from Evolve aggregations from inheritance heirarchies - Brian Foote and William F. Opdyke
- Look at Adaptor, Facade, Proxy from Design Patterns (GoF) and also the Stategy, which is mentioned here by Erich Gamma A Conversation with Erich Gamma, Part III
- Refactoring Catalog - Martin Fowler
- Refactoring posts - Martin Fowler

Tags: , , , ,

Apr 9 2009

Refactoring complex classes using Composition Part 2

Category: .NET | c# | Methodology | Refactoring | Visual StudioJonathan @ 04:07

Please Note: Please make sure you have proper unit test coverage on your classes, as you refactor.

From Part 1, I showed you how I initially split a large class into a few more, splitting the complexity of having the code in one place. However, you will still find that for a really complex class, there will still be quite a lot to do. Here are a few more composition based things to consider for continuing the refactoring process.

More...

Tags: , ,

Apr 8 2009

Refactoring complex classes using Composition Part 1

Category: .NET | c# | Methodology | RefactoringJonathan @ 04:09

Please Note: Please make sure you have proper unit test coverage on your classes, as you refactor.

Using Design Patterns which deal with compositional power, such as Wrapper, Facade, Adaptor, Bridge, Proxy and others are extremely useful for breaking large classes down. Rather have 10 smaller classes than 1 large one.

Well here is a very simple start to how to get your refactoring of that large class under way. Please be sure to compile your project after each step, to fix any errors, before moving to the next step.

More...

Tags: , ,

Mar 30 2009

How much should you design Upfront?

Category: .NET | c# | Design | Design Patterns | Methodology | Visual StudioJonathan @ 07:22

FeelGoodFactor

I follow the FeelGoodFactor principle. Requirements at first glance can be cloudy and messy. It can ambiguous and abstract, or it could just be plain daunting. However, you need to list what you can, and the attempt 'solves'. By solves, I mean a logical route to a solve, a prototypical solution to that problem, or at least common consensus by a few good men (cough). You need to get most of the areas in your head sorted, and then commit a bit of that solution in your head to paper and a review by your peers.

More...

Tags: , , , , ,

Mar 27 2009

A Simple Software Design Methodology


No matter what software development methodology you adopt, you will always be faced with 'design' that is between good and bad, between necessary and unnecessary, between complicated and over-complicated. Design, even if it is technically good, can have disastrous effects on the project, if implemented incorrectly, or creates discord within a team, misunderstanding. In fact there are so many reasons, it would be better just to tell you what good design is. That's if I could, but I can't!.
However, I can say that Design is one of the most important factors for a project, it influences time lines more than anything else. Underdesigning, or overdesigning, neglecting to think ahead far enough, not including certain implicit requirements can all add days and weeks to a project.

Most of the time, its in your hands

A project requires thought and understanding. It takes a wide range of thinking outside of the box, thinking realistically, but yet being extremely open to ways of improvement. Here are three activities that will definitely aid your methodologies, skydiving and chess and music.

More...

Tags: , ,

Mar 25 2009

ExtensionMethods repository

Category: .NET | c# | Design Patterns | Visual StudioJonathan @ 07:15

Oh what joy. Fons Sonnemans and Loek van den Ouweland have created a repository for ExtensionMethods. Go on, you know you want to. The site ExtensionMethod, allows you to submit your own creations to the community.

Now I had this idea, just around 10 minutes before I found the site, so they beat me fair and square. (By a mile). So therefore here is my top three ideas for the site, which I had, and hope they think about.

1. Grade it
Allow us to vote for it. However more than that, flag it with Compiled, Tested. Little icons that the site show next to each method.

2. Open Source the ExtensionMethod
Allow the community to edit the code, which will improve it over time. If I use it, and it fails because of something small, allow me to edit it, and solve the problem for everyone. Add original author, and contributor names to the list. Perhaps allow an 'Editor' per Type, to look after it and make sure its tested and complete.

2. Give us an Assembly
Run a build, once a month, compile all the snippets, which could be done automatically, if you get the correct data from the submitted snippet.
As part of the grading, is whether your automated compilation worked, when including the snippet. (snippet compiler like, compile on the fly and validate the method).

Now we can all download an Assembly for all these community driven ExtensionMethods. Updated: I found this nice, yet strangely odd set of ExtensionMethods for boolean.

Tags: , ,

Mar 23 2009

Frameworks and the MSDN Library


We all know that the learning curve for Frameworks are quite high. We all know that Frameworks demand commitment, and learning time. We know this because we struggle with it everyday, whether its Java or .NET, Swing, or MFC.

1991-1993, Ralph Johnson and others wrote about Recipes and Cookbooks. There have been papers on documenting frameworks for more than 15 years. MSDN has some of the flavours but none of it is actually polished, nor tailored to the audience and the way in which people seek information.


My D4 Software Frameworks Pattern Language points you to some Patterns for documenting Frameworks:

WritingReference
You must provide a reference of interfaces.
WritingRecipe
You need to provide examples of isolated features of the framework that a pure reference cannot show.
WritingCookbook
You need to combine a large amount of recipes.
SelfDescribing
Using tools and generators, you can generate documentation.


All of them are self explanatory, except let me add, amazing that blogs seem to be the number 1 source for this kind of information, as well as google tends to find things on MSDN better than MSDN finds on their own material?.

The Solution to the MSDN Dilemna

The last one (SelfDescribing) is where I am particularly keen. Not GeneratingReference but SelfDescribing Imagine if a method on a class called MethodA() had been marked with an attribute called TemplateMethod()

Well a Tool, would be able to highlight it for you. If you had a tree of all Types, TemplateMethods and Hooks, you would now better understand the way in which the types where constructed. You would now know that MethodA() called Method(B) then MethodC(). The internals of MethodA() ois not known, shown or cared for. But from a documentation point of view it is crucual for certain designs.

It is this, that is missing from MSDN, because it is missing from all frameworks. Documentation needs to be better, but cannot, until the compiled code, can be examined in a much more thorough way. Developers of Frameworks, must declare their intentions of methods, class and patterns by attributing metadata onto it.

So the solution, is to mark the .NET Framework Types with documenting metadata. Allow all Framework developers to utilize this metadata descriptions for their frameworks, and provide a tool to inspect it.

Tags: , ,

Mar 19 2009

A point about AgileDesign

Category: .NET | Design Patterns | Frameworks | MethodologyJonathan @ 07:00

Two comments came through to me regarding AgileDesign. It was pointed out that Agile is a loaded term, and perhaps I should look to rename it. Another aspect mentioned to me in an email, was that Extensible and Agile are probably the same or too similar to be different principles. The thing though, is that my AgileDesign, is exactly "Agile" Design, and although Extensible and Agile are both concerned with change, there is a very important difference between them.
More...

Tags: , ,