When you put a readme file into a folder that file is formatted and presented nicely through GitHub’s file browser. For example:

https://github.com/visionmedia/uikit

Scrolling down a little we can see a nicely formatted readme file.

GitHub strongly recommends adding a readme file to the root of your repository, but what I didn’t realise until recently was that it works for any folder in your repo. GitHub already has the best online file browser out there, but this specific feature can turn your source tree into your documentation.

For Robotlegs 2 I decided to try it out:

Async
MessageDispatcher
Extensions

Almost every package in the entire repo has a readme file. The best way to learn about Robotlegs 2 is to browse the source and readme files on GitHub.

Timing

To extend any framework you need to be able to hook into that framework’s initialization process.

That Damned Context

The Robotlegs 1 context class was, to be frank, rubbish – it set defaults, configured dependencies and controlled initialization. Worse, to hook into the initialization process or change the defaults, users had to extend the class itself resulting in the proliferation of funny looking words like SignalDrivenCovariantlyMediatedModularShellContext.

How Could You Let That Happen?

Extending the context was a silly idea – and I knew it at the time. It made me sad, deep down inside, but I knew that if I waited for a better solution to emerge the framework might never ship.

Also, my goals for Robotlegs 1 were:

1. Make it small
2. Make it fast
3. Release it

A ton of compromises were made to keep the number of classes down to an absolute minimum. That’s not how I usually write code. Besides…

Small Only Goes So Far

I always start by doing the simplest thing possible – it’s a good way to feel out a problem space. “What am I trying to do?”. The “how” doesn’t matter yet, but becomes important much later when I ask “How would I like to do this?”.

When writing actual code, however, I’m constantly faced with this annoying question: “Should I break this out?”. When doing the simplest thing possible I often decide against extraction: I’ve got a specific task to complete (like getting a test to pass) and I can refactor later if the idea proves itself to be worthwhile. Also, I know that extraction inevitably leads to a new set of design decisions. And I’ll have to start with a test – for something whose purpose I am only just discovering. And it ups the class count.

Keeping class count down for it’s own sake is almost always a bad idea. However, I don’t think Robotlegs 1 would have experienced the same adoption if it had had hundreds of classes instead of the quite digestible 15 presently in its belly. OK, 24 total if you add the interfaces.

When browsing open source libraries I get happy feelings from projects with a limited number of source files – it gives me a sense that if I really wanted to I could read through the entire codebase and understand it.

But there’s a point where that simplicity inverts. Profit becomes debt. Without good abstractions in place every participant in the system ends up doing too much. At that point the question becomes: “Do I need to introduce a new layer of abstraction?”.

Now You Have Two Problems

The introduction of a system wide abstraction layer fueled by a mid feature code extraction will do one of two things: it will strengthen the system or it will weaken it. A bad abstraction might solve the immediate design issues (like duplication) just fine but end up adding complexity and reducing quality overall.

Extensions? Timing?

So anyway, I want Robotlegs to be extensible in a sensible way. Users should be able to install custom extensions easily. Those extensions need a way to hook into the context initialization process:

Some extensions may need to be configured before others. Some may need to pause the initialization process and wait for a resource to become available. Some might directly depend on others and may need to wait for those extensions to be fully configured before self initializing. Some may only come to life after the entire context has been initialized.

It’s clear that the initialization process needs to be asynchronous. But without a good abstraction in place for dealing with asynchronous processing the context will be burdened with co-ordinating a complex series of events. Event soup is not delicious.

Events, Signals, Tokens, Tasks, Promises, Futures, Callbacks

There are a number of patterns for dealing with asynchronous processes. They have wildly different properties.

Some are low level, like the callback pattern. Some are high level, like the promise pattern. Some are guaranteed to be asynchronous, while others have the potential to be synchronous. Some are only good for observing. Some can be terminated, while others can be suspended and resumed. Some can be composed and chained. Some necessitate the instantiation of throw-away objects and put stress on the garbage collector. Some put stress on the stack.

Take Your Pick

I wanted something fairly low level that enabled asynchronous processing without adding unnecessary overhead in the cases where things could be synchronous (or skipped entirely).

I tried a number of things. For the most part: floppy, verbose and annoying implementations that moved the core problems around in less-than-useful ways.

Dispatch

Slowly it dawned on me. In this case all I wanted was an asynchronous message dispatcher. With a well defined set of callback conventions I could write something resembling an Event Dispatcher but without the overhead of creating throw-away objects (events) and with the ability to suspend and resume the dispatch when desired:

Some Async Conventions

The Message Dispatcher

Initialization, Extension, Please Continue

Very well. Suppose that context initialization comprises 3 steps: preInitialize, selfInitialize and postInitialize. When told to initialize the context moves through those steps in sequence. Anyone can listen in and halt the process as required at any point. What we end up with is in essence just a simple state machine where the observers have the potential to be guards.

The End

Well, that’s where the re-write started anyway.

Robotlegs 2

p.s. I dropped a bunch of stuff from the version2 branch. I’ll be going back to pull out any functionality that might have been lost shortly. If you come across anything that’s missing feel free to adapt it to the new codebase and send a pull request. Or drop an issue on the tracker. For quick reference, here’s the old version2 branch: version2-old

Bad “I did this” form:

I had a cup of coffee, went for a walk, and changed some code.

Better “This commit does this” form:

Adds unmap() to the command map API.

A commit message should describe the commit, not the process you went through to create it – it is not a diary.

[Test]
public function null_criteria_should_not_match():void
{
  assertFalse("passing null should return false", instance.match(null));
}

When reading the test above I have to do a lot of scanning.

First I see the string message in the middle because it jumps out. The message is redundant as it’s included in the test name. If I change the test I’ll need to change both the method name and the string description. I can see that the string message would be useful for a test with multiple asserts, but that’s generally not a good idea.

After reading the string I look to the right to see what is being tested and mentally try to evaluate it.

Then I look to the left to see what the expectation is, possibly flipping the evaluation I just did to match the expectation.

It’s disconnected, and it’s hard work.

Consider this instead:

[Test]
public function null_criteria_should_not_match():void
{
  assertThat(matcher.match(null), isFalse());
}

Now I just read normally: top-to-bottom, left-to-right. I read the test name, look at what is being evaluated and see what is expected.

While doing some work on multi-context view auto-wiring I wrote a little utility that iterates through the containers in a given display object container and builds some useful stats.

If you have a moment I would love it if you could run it against your Flex or Flash app and post the results in the comments. Please also indicate whether you ran it against a single complex component or an entire app, and whether it was Flash, Flex or Mobile.

GitHub: https://github.com/darscan/boyblack-toolkit

ZIP download: boyblack-toolkit

Usage:

trace(new DocStats(doc));

Sample output:

Display Object Container Stats

All Container Stats
Containers:             521 total
Children per container: 8 max, 1.16 avg
Depths (distance):      29 max, 18.45 avg
Unique container types: 86 total

Unfiltered Container Stats
Containers:             153 total
Children per container: 8 max, 1.69 avg
Depths (distance):      26 max, 16.98 avg
Unique container types: 65 total

Filtered (mx., spark., flash.) Container Stats
Containers:             368 total
Children per container: 8 max, 0.94 avg
Depths (distance):      29 max, 19.07 avg
Unique container types: 21 total

Injection Everywhere

Automated Dependency Injection is a handy way to wire the component parts of a system together. But systems are comprised of components at varying levels of abstraction. Some are high-level, domain specific abstractions, whilst others are low-level implementation details.

If every object in a system is given the same level of importance, thrown into a DI container, and made available to every other object, the layers of abstraction become very hard to see. The container becomes a mixed bag of configuration details, value objects, sub-systems and goodness-knows-what-else.

Does a URL (a very specific, low-level configuration detail) really deserve to be sitting in a flat container right alongside a high-level, domain specific model? Certainly not!

It can be difficult to determine what is and what isn’t appropriate for automated Dependency Injection. It depends on the system you are building, and is something that comes with time and experience. I’m certainly still struggling with it on a daily basis.

Here’s a related post on the matter:

http://www.higherorderlogic.com/blog/2011/07/30/is-dependency-injection-like-facebook/

Interfaces Everywhere

Program to interfaces, not implementations. Interfaces decouple us from implementations, they are good, but, as always, there are some subtleties worth considering.

Many languages support explicit interfaces: contracts with absolutely no implementation details. But every object also has an implicit interface – the public methods and properties exposed by that object.

Creating an explicit interface for an object that will only ever have a single implementation is a violation of the DRY principle as the explicit interface duplicates the implicit one.

This happens most often when the interface is large and acts as a “stand-in” describing a class rather than a piece of behaviour. Sure, you *could* swap out the implementation at some point, but honestly, so much of the implementation has already leaked out into the interface that there is very little point in doing so.

Program to interfaces, but remember that sometimes a small implicit interface is better than a large explicit one.

Another related post:

http://lostechies.com/derickbailey/2008/10/20/dependency-inversion-abstraction-does-not-mean-interface/

Stupid names, useless comments, multiple levels of abstraction, poor error handling, super deep nesting, etc etc etc. It pretty much breaks every rule in the book. But the best bit has to be this:

Yes, that’s right, a five dimensional array!

The State Of The Game

There are some great Flash and Flex application frameworks out there right now. Mate, Swiz and PureMVC (update: and Parsley!) stand out. The authors of these frameworks realized that the Flash Platform is different enough to the JVM to warrant a fresh approach to application design.

Someone mentioned recently that for such a young language (referring to Action Script 3), it’s quite surprising how many frameworks have sprung up around it. I’m not surprised at all: rich internet application development is complicated.. and it’s a pretty recent field in the grand scheme of things. It brings new (and often subtle) twists to traditional web and desktop software development. Writing elegant, maintainable code is hard enough as it is, but doing so on a rapidly evolving, heavily interactive platform.. well, people are still working on the best way to approach that (unless I missed the big news – in which case you can stop reading right here).

Hence all the groovy new architectural frameworks popping up. They share some common goals:

1. Help developers write good, clean, understandable, testable, maintainable code
2. Help them write that code faster
3. Provide an easy-to-use mechanism for application/context/module subsystem inter-communication
4. Provide an easy-to-use mechanism for wiring distinct parts of the application together whilst keeping those parts loosely coupled

And they succeed. To various degrees. I think they’re all pretty cool.

A Poke In The Back With A Sharp Stick

So why build another one?

1. For fun – it’s how I learn stuff
2. Because I find the other frameworks critically flawed

What kind of “critical” flaws?

1. Singletons (big “S”)
2. Central/Static Event Dispatchers
3. Using the Display List as an Application Event Bus
4. Casting
5. The Service/Model Locator Pattern
6. The Presenter Pattern
7. Injecting into View Components

And what’s wrong with those things?

They are bad ideas:

1. The Singleton – Bad Idea

The standard Singleton implementation (that static getInstance method) is severely flawed. Unless you are writing device drivers, there is almost no excuse to touch a Singleton with a sharp stick.

Singletons bring bags of hurt to frameworks and applications.. suddenly, trying to build a modular application becomes an overly complicated affair, and unit testing becomes a nightmare. Singletons are viruses – they infect every class they touch.

And Multitons? If Singletons are evil, Multitons are diabolically evil. What makes the Multiton pattern incredible is that it manages to chump the Singleton as the worst Design Pattern Of All Time – no easy feat, and certainly the work of an evil genius with a wicked sense of humour. Not only do we have all the problems of the classic Singleton, we throw a poorly designed Model Locator into the mix – to pull out these horrendous Singletons we now need to use String keys.

Contextual singletons (as made possible by Dependency Injection frameworks) are a much nicer solution, they don’t require any extra (fluffy, nonsense, ill placed) code on the target classes themselves, and they allow identical applications/modules to exist side-by-side in the Virtual Machine without fighting and mass confusion. Which leads me to..

2. Central/Static Event Dispatchers – Bad Idea

As convenient as it is to use, a Central Dispatcher is a really bad idea. Another Singleton effectively. Pop two apps into the same SWF and watch, with excitement and glee, all the cross-talk that occurs – both apps responding to each other’s events. Oh noes!

Architectural frameworks generally provide you with an application event bus/channel/dispatcher to “chat” on, but this should be localised to the application itself (or some other context). Which leads me to…

3. Using the Display List as an Application Event Bus – Bad Idea

I find this one fairly disturbing too: dispatching system/application events along the display list. No!

A View is just that: “A view”, not “The view”. And don’t get me started on those innocent looking Event Maps! No, let’s move along…

4. Casting – Bad Idea

Besides wasting space and annoying programmers, casting distributes knowledge throughout a system – casting requires that you look elsewhere in your codebase for the “real” type.

And it weakens our lovely compile-time type checking (albeit temporarily), sending us back in time to our unhappy days building complex applications in the Flash IDE. And it’s boring. And it often occurs because of..

5. The Service/Model Locator Pattern – Bad Idea

Classes should not be responsible for “fetching” their dependencies – this is a separate responsibility that belongs somewhere else entirely – they should only contain code for doing their job. When classes reach outside to fetch things from the application/context they sneakily hide their dependencies away from the outside world.

Unit testers will despise you (which is a serious problem if you are writing your own tests) because it becomes incredibly hard to figure out how much set up needs to be done to write even the smallest of tests. You have to look inside the class for any calls to the Service Locator to find your direct dependencies, and then you have to look inside each of those classes to find theirs and so on. No no, that’s just cruel.

6. The Presenter Pattern – Bad Idea

Ok, it’s going to be tricky to back this one up. But think about it this way: the Presenter pattern requires that you modify your View component (to add a reference to a Presenter). Not a biggie, but once you’ve done that you’ve started coupling your View component to your application/context – a slippery slope.

I think the Mediator pattern is a much better fit for Flash and it’s Display List, and even more-so when it comes to Flex (and other UI frameworks with complex component life cycles).

It is far easier and cleaner to “wrap” around view components and poke their APIs than to have to modify (extend) them to make space for their Presenter references. Leave those components alone, leave them to the component developers, you’re supposed to be writing an application. While we’re on the Presenter pattern, let’s take a look at something dirty one might do in an attempt to salvage it’s reputation..

7. Injecting into View Components – Bad Idea

Besides being incredibly slow and wasteful (especially for Flex UIComponents), injecting directly into a View component couples it to your application/context.

View components, with any hope for reuse, should be as self-contained as possible. They should expose an API and dispatch Events. They shouldn’t be dependent on the application they are in or the framework it happens to be using. Give ‘em ViewModels (M-V-VM) if you must, but don’t go and couple those ViewModels to your application, and certainly don’t inject them.

Wrapping Up This Micro-Post

Well that’s just your opinion, dude

Yeh, but I’m pretty proud of my little 7 point list there (cos I’m an OOP noob, and this stuff gets me amped). Using Dependency Injection I was able to avoid all those nasty things when building my own PureMVC-like framework.

But that just shifts the problem somewhere else

Yes, somewhere more appropriate.

Besides some convenient implementations (in the mvcs package), and some marker interfaces (in the core package) RobotLegs essentially provides two things:

1. A Command Factory – for binding Commands to Events, and
2. A Mediator Factory – for handling automatic Mediator creation and registration

Everything else is handled by a Dependency Injection framework and an Event Dispatcher.

Note: If you’ve been through all this before, I apologise, it’s new to me.. I’m a little slow.

Beware: the current default implementation of RobotLegs makes use of annotated setter injection. This breaks encapsulation, is open to misuse, and runs the risk of leaving objects in partially initialised states, but it’s very convenient! You can swap out SmartyPants-IOC for a Dependency Injection framework that performs constructor injection if you really want to play it safe.

I’ll admit straight-up (albeit as a footnote) that I never really gave Cairngorm much of a chance – preliminary research led me to demos, documentation and diagrams that screamed poor design and foreshadowed immense struggle. I’m sure there is a way to build a well designed Cairngorm application, but it looks like it’d take an awful amount of effort.. and code. And it probably wouldn’t be very much fun.

UPDATE: Removed some words that made me sound like a douche bag.