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.

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/

Moreover they can all perform automatic DI by parsing class metadata. It would be grand if the common DI related metadata tags could be standardised. That way we really could write code that is decoupled from any particular framework.

I’ve started a little document over at GitHub:

http://github.com/darscan/AS3-DI-Metadata

I don’t know the libraries well enough to fill in all the details, so if you could fork the repo and edit the doc that would be great! Also, the format/layout could be better, so if you have any ideas on that front.. edit away.

robotlegs/robotlegs-framework/blob/master/src/org/robotlegs/core/IContextProvider.as#L16

Don’t do that you naughty sausage! Your codebase will evolve (if all goes well), and line 16 will be replaced by a newer, shinier string of characters. Or, in this case, it’ll point to something that no longer exists.

This, on the other hand, is more likely to stick around to haunt its author (me):

robotlegs/robotlegs-framework/blob/v1.1.2/src/org/robotlegs/core/IContextProvider.as#L16

Select a tag before you link to your fancy code (“Switch Tags” under GitHub‘s “Source” menu).

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!