flAir :: flashFlexAir

TDD: The Starwars Answer vs The MacGyver Principle

2010-10-28T12:56:00.011+01:00

"But what if you write a bug - like a typo or something - into the test? I mean, your tests aren't going to be perfect, are they?"

This is a genuine question someone - understandably - asked me earlier this week when I was introducing them to the idea of TDD.

I have two answers to this question:

1) The math answer:

If P(Error) is the probability of any line of code you write containing an error, and you write t lines of test code and tn lines of production code, where n is greater than 1, then bugs in both tests and production code can only slip through when they coincide, and you will fix tn bugs in production code for every t bugs in the tests.

And as P(A + B) = P(A) * P(B) then you vastly reduce the number of undetected bugs caused by genuine code errors - eg accidental assignment, wrong operations, wrong variable names etc.

If you don't speak Math, the outcome is many, many fewer small bugs.

2) The Starwars Answer:

"These are not the bugs you are looking for."

No - really, typos and wrong negatives are cool to find, and do cause many wasted hours debugging, but this isn't why I do TDD.

TDD is most powerful when it really hurts. The pain comes because you realise that you have written, or planned to write, some code that is hard to test. TDD pokes you right in the coupling. It stabs you with your own statics and shoves your crappy assumptions right...

... you get the idea?

When you write a test for a class, or a unit of functionality, you are trying to do that outside of the application. So all those hooks and shortcuts and bits of spaghetti that seem so handy inside your app swiftly start to look like what they are: problems.

But there's something TDD brings to your attention that's even harder to swallow...

TDD goes against the MacGyver principle

TDD exposes to you the numerous pathways through your code. If you're testing something as simple as a form with a set of radio buttons, you have to test every possible option for that radio button selection. You imagined you were going to write half a dozen tests for this class and suddenly you've got 15. And you can still think of more special cases that aren't covered.

This is a head-fuck because we like to pretend, to ourselves, that what we're trying to do is much, much easier and less complex than it actually is. I suspect there are very few genuine pessimists* in programming. We are self-selected MacGyver types with a tendency to see the solutions in any situation.

This process relies on the confidence trick of pretending to yourself that what you're undertaking is pretty straightforward, really. We have to turn a blind eye to the factorial expansion of pathways through our code presented by each new 'tiny' feature, because the alternative is lying awake at night wondering whether we've really covered every important combination of user actions, and knowing that we're never going to hit the deadline.*

Many flash programmers are just as badass as MacGyver. They bravely code ahead, pushing to the side the concept of failure - they know they can cross between these two structures using only a coathanger and some magic strings (static) because there is no room for any other possibility.

And hell, it works out a lot of the time. We all built some awesome stuff in as1 when we didn't even have compile-time-checking or type safety. But if you're still MacGuyver coding today, I have one piece of advice: Don't look down.

* There are plenty of us who are cynical, but I think that's distinct from pessimism. We probably believe there are solutions to most problems, but that people are too damn stupid / greedy to allow them to be implemented.

** In reality, nobody ever hits the deadline with MacGuyver coding, but they at least agree to the deadline, which most of the time is all the boss is looking for. With TDD, nobody agrees to the deadline the boss was hoping for. As always, TDD just shifts that pain forward in the timeline.

Don't dehydrate your code

2010-10-15T14:30:00.007+01:00

DRY (don't repeat yourself) is one of the first principles you learn as a fledgling coder.

When you build your first loop, you're embracing DRY, and all the wonderful code-shrinking that comes with it. And it feels good, and we're taught to seek out repetition as a terrible code smell, and do away with it as soon as possible.

But it's possible to be too DRY - no, really, it is.

When considering repetition for refactoring, there are two different questions we can ask:

'Are these two blocks of code the same?'
'Do these two blocks of code serve the same purpose?'

The different questions can lead to different answers for the same blocks of code. If the answer to question 2 is 'no' then you potentially create another, harder, refactor down the line, when you realise that the operation needs to change for one case, and not for another.

These too-dry refactorings leave their own particular code smell - optional parameters. They're not always a sign of overly-dry code - the robotlegs context takes an useful optional parameter for 'autostartup' - but when the optional parameter is littered through the code inside the function, it can be a sign that your code has become dehydrated and you'd be better off splitting it back out again - and either living with a little repetition or slicing the functionality up differently.

We make a similar call when we make decisions about inheritance and interfaces.

ClassB might have all the same functions as ClassA, and a few extras of its own, but unless ClassB truly "is a" ClassA, then there's no reason why the two should evolve together in the future. Better to tolerate the repetition because it correctly represents the cognitive model behind the application.

Similarly, unless ClassA and ClassB share obligations, and could potentially stand in for each other without your application logic losing sense, they shouldn't implement the same interface. Even if they have the same functions. Yes, even if they have the same functions.

Shut up with the "it's less code" thing

Of course all of this requires us to recognise that "It's less code" is never a refactoring justification in itself. Often, great refactorings create more code, not less. The objective is always to make your application easier to maintain, change and grow.

So - unless you're writing your code for a programmable calculator from the 1980s, any time you hear yourself think or say (or write, I see this a ton on the robotlegs support forum) "but it's less code this way..." just give yourself a little slap. There are often good reasons to take the fewer-classes approach, but they need to be more fleshed out than 'less code'.

The scarce resource is your brain. Your attention, your cognition, your working memory, your mental-models. And of course your time. An over-dry refactoring (particularly for the sake of 'less code') that requires a reversal later is expensive in terms of all these scarce resources.

Embrace (selective) repetition

A criticism of robotlegs is that you can end up with code repetition of very simple blocks of code in your Commands and Mediators, as well as a lot of custom Events. It *feels* weird to type the same code twice or three times to translate 3 different Events into the same corresponding action. But, in my mind, this is part of the power of the Command pattern.

Each Command encapsulates the logic steps required to respond to that situation - and they can freely change in future without impacting upon each other. The code repeated in your Commands is usually cheap and simple - if it's not then think about farming some of the logic out to a helper of some kind.

So don't sweat the 'glue' code having similarity between Commands and Mediators sometimes. Code that is dehydrated is just as tricky (sometimes trickier) to work with as code that needs a little DRYing off.

TDD: Make your intentions clear(er)

2010-10-07T20:12:00.005+01:00

A habit I've got into recently is creating more and more classes specifically for the purpose of testing.

If the class extends a class which is meaningful to my application it's called ThingSupport (where Thing is the name of the Class it extends).

If the class is extending a more generic class - eg Sprite, or Command with an empty execute - then it's called SampleThing. (Again, Thing is replaced with the name of the Class it extends).

So - my source library now contains a growing number of classes like:

SampleCommandA

SampleCommandB

SampleVO

SampleEvent

UserVOSupport

MainMenuItemSupport

AccountModelSupport

The Support classes tend to populate the constructor parameters.

So if the constructor of UserVO is

public function UserVO(key:uint, username:String, password:String, jobTitle:String etc )

then the constructor of UserVOSupport is

public function UserVOSupport(key:uint = 1)

{

super(key, 'username_'+String(key), 'password_'+String(key) etc)

}

Now I can create a dozen UserVOs with distinct properties only passing an incrementing uint variable to the constructors. Lovely ... but...

...it's not about typing less

The ThingSupport classes do two things: they make it easier for me to instantiate the class, but also they isolate my tests from changes to the constructor of the Thing classes. If I update the Thing constructor to include another param, or change the order, I don't have to touch my tests - I just make a matching change in one place - ThingSupport.

When my coder-friends protest that they find TDD tiresome because if you make changes you have to do loads of maintenance on your tests, this makes me think that they're not isolating their tests well enough.

So what about the Sample classes?

What's the point in creating a SampleEvent? If the class/test requires a particular class why bother to create a sample class as well? Why not just use Event?

This is the newest thing I've added to my workflow - and hey, by the end of next week I might have changed my mind - but I'm experimenting with using it to make my intentions clearer in my tests.

As in - what's *real* and what's just test scaffolding. Particularly in integration tests where multiple classes are working together. The use of Sample as a prefix is helping me keep my head straight on which elements are being tested and which are simply provided to wire things up.

That way, when I look through my code and it uses SampleCommandA I know that the SampleCommandA is not part of what's being tested - it's just fodder for the test.

Couldn't you just use mocking?

I do use mocking (with mockolate) a lot. Actually I tend to use stubbing / verification - via mockolate. I use it to mock interfaces for services so that I can verify that a method on that service has been run by a command with the correct treatment of the event payload, even before I've implemented the concrete service to the interface.

I also mock (for verification) framework elements - injector, CommandMap - to verify that runtime mappings have been made correctly - again, usually in Commands. It's easy to think of Commands as being so banal that they're barely worth testing, but a Command that doesn't actually run the method on the service, or doesn't manipulate the event payload correctly, or fails to make a mapping could potentially lead to hours of debugging once compiled into the wider app.

Focus on minimising your WTFs per minute

As @mark_star tweeted this week: "The only valid measurement of code quality is WTFs/minute" (clean code).

I believe the use of Support and Sample classes is significantly lowering my WTF rate. It feels good.

I'm starting to think that a focus on "less typing = better" is really dangerous in a coder. I can type at 80 wpm. Can I code at 80 wpm? Can I f***! This 'more code = slower' belief is part of what keeps people from embracing TDD.

But it's a dangerous obsession for more than one reason. The search for the perfect IDE may actually lead to an increase in the kinds of WTFs that go on for hours and even days.

@_ondina posted some wisdom on the robotlegs board today about the value of being intimate enough with your code that you can write it by hand. We were discussing code generation tools for robotlegs at the time - and she made the valid point that if you rely too much on code generation tools then there's a chance that small errors - [inject] vs [Inject] - creep in to your code and you have no way of diagnosing them, because you haven't built up enough experiences of what looks right for your brain's pattern recognition system to let you know what is wrong.

Food for thought.

Harnessing the Drive in Test Driven Development

2010-09-28T10:56:00.012+01:00

I had an interesting exchange with someone on twitter last night - he'd been working on some math, that kind of looked right to him now, but had no way of knowing whether it was 'right' or not.

I teased him that he should have done TDD, but he felt that TDD meant you had to know your API ahead of coding, and his situation was evolving, so that ruled out TDD.

I was arguing that actually TDD is ideal for when you're not quite sure where you're headed - a view point that didn't fly with his experience - so this is an attempt to further explain that sentiment.

Your brain and body will try to resist TDD

A common barrier to adopting TDD (this is what my colleagues and peers come back with over and over) is "I don't know enough about what I'm doing to write the test yet."

My response is that if you don't know enough about what you're doing to write the test yet, you sure as hell don't know enough to write the code yet!

Test Driven Development shifts a ton of that 'wtf am I trying to do?' pain to the front of the process. And that's hard to get used to. It exposes what you don't have clarity about - when you really just want to get on and pretend you do know where you're headed.

So - how can TDD possibly help when you don't have a clear idea of your direction?

TDD means more than one kind of test

I do 3 kinds of tests. End-to-end tests, integration tests and unit tests. Combining all 3 test varieties is the key to driving evolving development. (Which, IMHO, is the only kind there really is.)

I write the end-to-end tests first. An end-to-end test describes a user story. If you don't know what your user stories are then you need to get those together before you take another step. User stories will be numerous, even in the simplest app, so don't overwhelm yourself - just start with the shortest, simplest user story in your requirements.

User story / end-to-end tests

In a complex app, the user stories are rarely actually end-to-end (startup to shutdown) but they capture a unit of meaningful interaction with the application.

There is only one user story end-to-end test in each test case. Some examples from my current app include:

LibrarySimpleSearchReturnsInvalid

LibrarySimpleSearchProducesNoResults

LibrarySimpleSearchProducesResults

LibraryShowAllShowsAllItems

LibraryAdvancedSearchProducesResultsByType

LibraryAdvancedSearchProducesResultsByExclusion

... you get the idea.

In each case, the test recreates the user experience from the moment of opening the library (which is a searchable, browsable set of resources of different types - jpg, document, video etc) until they receive their search results.

This means that it's a UI driven test. I have the test code enter text, push buttons etc, and I delve into the display list to verify that the correct items / text etc have appeared on screen at the end, and usually this is asynchronous to allow time for transitions.

Integration / functional area tests

These test a component of functionality. For example the search window, or the results viewer.

Unlike unit tests they make use of real concrete instances of the classes needed to fully instantiate and work with the components being tested. If the functional area depends on the framework to wire it together, the framework is instantiated (robotlegs in my case) in order to wire up the component.

In my current app I have an integration tests for the main menu:

NestedMenuTest

This menu has multiple layers of nested items and has to collapse all / expand all / auto-collapse and so on in response to checkbox clicks. My integration tests check that the scrolling behaves itself when the items are being expanded/collapsed.

test_max_scroll_then_collapseAll_resolves

test_mid_scroll_then_expandAll_keeps_top_visible_item_in_place_and_scales_scroller

and so on...

Usually, integration tests are event driven - I kick it all off by manually firing an event. Often, but not always, they require you to use the display list to verify the results.

Unit / API tests

These test that a specific class does what it is supposed to. They test all the public (API) functions of a class, sometimes multiple times if there are errors to be thrown or alternative paths through the class itself.

There is a wisdom that says test all API except for property accessors. I tend to test my property accessors as well, because there is no limit to what I can screw up and it's faster to get them right them at this point than when the error emerges later.

Instead of using concrete instances of their complex dependencies (eg services), my unit tests make use of mocks (using Drew Bourne's Mockolate) to verify that they've acted upon those classes correctly.

If I was testing that a command pulled values from the event that triggered it, did some jiggery pokery with these values and then used the results in calling a method on the appropriate service, I would mock the services to verify that call, rather than try to test against the results of the call.

Here, I've mocked the two services, lessonLoaderService / joinedLessonLoaderService:

public function testLoadsLessonIfRequestEventNotJoinedLesson():void{
  var lessonLoadRequestData:ILessonLoadRequestData = new LessonLoadRequestDTO("test","testSwfPath", true, '', false);
  var testEvent:LessonDownloadEvent = new LessonDownloadEvent(LessonDownloadEvent.LESSON_DOWNLOAD_READY, lessonLoadRequestData);
  instance.event = testEvent;
  instance.execute();
                                                                       
  verify(instance.lessonLoaderService).method("loadLesson").args(equalTo('testSwfPath'));
  verify(instance.lessonLoaderService).method("loadLesson").once();
}

public function testLoadsJoinedIfRequestEventIsJoinedLesson():void{
  var lessonLoadRequestData:ILessonLoadRequestData = new LessonLoadRequestDTO("test","testSwfPath", true, '', true);
  var testEvent:LessonDownloadEvent = new LessonDownloadEvent(LessonDownloadEvent.LESSON_DOWNLOAD_READY, lessonLoadRequestData);
  instance.event = testEvent;
  instance.execute();
                                                                       
  verify(instance.joinedLessonLoaderService).method("loadLesson").args(equalTo('testSwfPath'));
  verify(instance.joinedLessonLoaderService).method("loadLesson").once();
}

Putting it all together

Often, we put applications together from the bottom up. With half an eye on the requirements, we start thinking about interfaces and event types and functional areas. This works, but it can also result in some YAGNI code, as well as throwing code out that seemed like it was going to be relevant until you realised that the requirements weren't complete.

I think there's more sanity in a work flow that runs this way:

1) User story

2) End-to-end test that verifies this user story (or part of it - this can evolve)

3) Integration tests for the functional areas required to fulfil the end-to-end-test

4) Unit tests for the classes required to provide the functional areas

5) Code to pass 4, to pass 3, to pass 2, to verify against 1

... and when you have no fails, then add to 2, add to 3, add to 4, do 5, rinse and repeat etc.

Doing it this way, the consequences are:

A lot of head scratching early in each cycle (creating end-to-end tests is hard).
Usually having failing tests in your test suite, until you're done adding a feature/user story.
Always being able to tell what the hell you were doing when you last stopped ... because your failing tests make that obvious.
Never writing code that doesn't actually add value to the project by contributing to the implementation of a user story.
Always working towards a 'shippable' goal, which is good for the client (and your cash flow if you bill against features) and also allows real user feedback to improve the work still to be done.
Reduced cognitive load for you at a micro level - you fix problems in the code while that part of the code is what you're focussed on.
Reduced cognitive load for you at a macro level - you don't have to hold the 'where am I going' part in your head, or remember to test manually, because your user story tests have that covered.

I would argue that as a consequence of those last two there's a bigger reward: being able to show up more fully for the rest of your life. A bug, or a concern about whether I've really implemented feature X correctly, impacts on my ability to be present for my family. I'm kind of not-really-there at dinner, because 90% of my brain is background processing code stuff. This still happens with TDD, but it happens a lot less.

So, if you don't find that TDD is improving your code and your process - not just your output but also your enjoyment - then my (cheeky) suggestion is that you've not discovered what it's really about yet.

In my experience, TDD is fun. Chemicals in my brain fun.

PS. If you haven't already got it, this book is essential reading on harnessing the Drive in TDD: http://www.growing-object-oriented-software.com/ Props to Joel Hooks for recommending it.

Air Swf loading anomolies

2010-09-03T22:46:00.008+01:00

The application I do most of my work on (An AIR 1.5 app) loads swfs in 2 ways.

There are modules of functionality that are loaded into the application sandbox using the secure loading method that I've blogged about here before.

There are also 'lessons' which consist of multiple swfs that are loaded into the non-application sandbox. If a lesson consists of 4 swfs then they are all loaded, and then they are added to / removed from the stage as the user browses through the lesson. When another lesson is loaded the previous lesson swfs are first unloaded.

These swfs are having code injected into their timelines, but they also contain code at timeline depth and in nested MovieClips. This is generally just simple 'show this label on MouseOver' functionality. Nothing fancy.

I found a few months ago that loading the swfs serial - as you would expect to do [by waiting for one to INIT before loading the next] - caused the code in the nested MovieClips to *often* fail - on Mac or PC. I tried to track down the cause of this, and through my experiments I discovered that loading the swfs parallel seemed to solve the problem. So, unable to discover a reason I went with the approach that worked.

Now the problem has reared its ugly head again - but only on PC. On Mac, all code works fine all the time.

On PC (Windows XP), the timeline code, and the injected code, are always fine. But MovieClip code - whether done in a separate class file or just put into the MC timeline, is borked in SOME swfs, depending on what order the swfs INIT in.

So far I've discovered the following:

1) Loading the swfs serial, MC code is frequently borked on Mac or PC.

2) Loading the swfs parallel, code borking is dependent on the INIT order. [Might this indicate that the swf isn't fully loading when it INITs first?]

3) Whether the code is directly in the MC, or just in the MC timeline, it's just not there - even a stop() doesn't work.

4) I've replicated the problem with simple assets (a 2 frame MC with diff coloured squares and a stop() on frame 1), guaranteed not to clash with any other assets in any other swf being loaded.

5) The swfs most likely to be borked are those with the largest file size. BUT removing some assets to reduce the file size doesn't appear to help.

6) The swfs are currently being exported from Flash Pro CS4. I'm downloading CS5 trial just incase it helps. They're FP10.

7) Some swfs are only borked if they INIT first. Some are able to tolerate being the first to INIT without problems. Some are borked if they're first OR second (of six in that case) to load.

8) Adding a pause after all the swfs have loaded, before I do anything else, makes no difference.

9) Air runtime is 2.0.3

--- EDIT - conclusion

I think I've found the source of the problem.

The load order and the broken movieclip code are both symptoms of the same problem: the swf has not loaded into memory correctly.

The broken swfs are usually the largest, and when they INIT ahead of much smaller swfs it's probably a sign of incomplete loading, hence the correlation with Level-1 code not running. (Level-0 is timeline, level-1 is code inside MCs on that timeline etc).

Having run the tests hundreds of times I've found that this problem occurs approximately 50% of the time in a Parallels-XP virtual PC, and occasionally on a Windows 7 machine that has been down-versioned to windows XP (and hiccups in many other areas). So far it does not happen on a Mac book pro bootcamp XP install, or a stable Vista install.

I guess it's a genuine thread crash in the Air app, most likely some sort of memory issue?

I have not been able to find a way to prevent the problem from happening. Instead I have a work around:

Each swf contains a MC on the timeline on frame 1 with a line of code with the sole purpose of notifying the application (via the sandbox bridge) that level-1 code has been loaded correctly. If this notification is not received for a particular swf by the time the 'COMPLETE' event fires, the swf is deemed to have loaded incorrectly, and is unloaded from memory and loaded again.

This process is repeated until the load is correct. The files are local so the delay to the user is minimal.

Using actionscript 3 to inject code into the timeline

2010-07-13T17:12:00.008+01:00

Two undocumented handy features from AS3 for working with the MovieClip timeline:

frame1();

Which runs the code on frame 1 of the timeline, with corresponding functions for any frame that contains code - frame99(), frame354() etc.

addFrameScript(frameNumber:int, newFrameActions:Function):void

Which adds the code specified in newFrameActions at the frameNumber. Note that this is a zero-based frame number, yet frame1() is one-based. To add code to the first frame of an MC and then call it, you would do:

mc.addFrameScript(0, firstFrameActions);

mc.frame1();

addFrameScript will overwrite any existing actions, so if you want to augment and not just replace the code that is there, you'll need to first grab the existing frame code and then include that in your new function like this:

var oldFrameActions:Function = function():void {};

if((mc['frame23'] != null) && (mc['frame23'] is Function))
{
oldFrameActions = mc['frame23'];
}

var newFrameActionsFrame23:Function = function():void {
oldFrameActions();
// add new code here...
}

Of course all of that is much better wrapped up in some portability that doesn't care whether it's frame 23 or frame 99 etc. I'm using a class for that - http://gist.github.com/474159

You feed it a MovieClip and you'd probably want to hold a reference inside that MovieClip as well because one of the other uses is in overriding gotoAndPlay() so that it will rerun the code in the current frame without having to move the playhead (assuming frameScriptManager is a reference to an instance of the class in the gist):

override public function gotoAndPlay(frame:Object, scene:String = null):void
{
var frameNo:int = this.currentFrame;

super.gotoAndPlay(frame, scene);

if(this.currentFrame == frameNo)
{    
var frameFunction:Function = frameScriptManager.getFrameScriptAtFrame(frameNo);
try {
  frameFunction();
}
catch(e:Error)
{
  trace(e.getStackTrace());
}

}

}

The class, and in particular the getFrameScriptAtFrame() function also deals with the major gotcha: even once you've added additional code to the timeline at frame 1, the frame1() function continues to only run the actions that were present in the MovieClip (or Fla) timeline when it was published.

An alternative to rerun the current frame actions is to call Stage.invalidate() before the gotoAndPlay() - which is OK unless your content, like ours, is loaded into a sandbox that doesn't have access to Stage.

--- ADDENDUM ---

I have now also discovered that the visibility of the frame1() function is internal - so unless the FrameScriptManager is compiled into the same package as the SWF / MovieClip base class, these will show up as undefined (annoyingly no more helpful error is thrown).

So - the workaround is that your MC to be injected should implement the following function:

    public function getFrameScriptAt(frameNumber:int):Function
   {
       return this['frame'+frameNumber];
   }

This is also specified in the IInjectableTimeline interface I've added to the Gist file. However, the FrameScriptManager class itself doesn't require an IInjectableTimeline, but will accept a vanilla MovieClip because the complications of ApplicationDomains for content loaded at runtime, plus variation in where the FrameScriptManager is complied (in the parent swf or in the child swf), make it tricky to roll a one-size-fits-all solution with strong typing.

So - the interface is there to help you keep yourself honest. Unfortunately there's no compiler enforcement in this case.

--------

What's the point of all this? Well, in our case the swfs being targeted for timeline code injection are animated lessons. These lessons also need some code in them to address the application they run in - so that they can ask the main message window to show a title, or offer a download, or some instructions, or set the status of the play / pause button at the end of a section. Previously we did this using frame code, but this was hard to test and maintain. Instead we now specify most titles, instructions, download paths etc in an external xml file which is quick to edit.

At runtime the xml file for each lesson is processed and the relevant actions are added to the timeline of the lesson swfs, meaning that as far as the application is concerned these new, easier to manage (for us and our client) lessons behave exactly like the old ones.

Programming for the slowest processor

2010-02-26T16:02:00.003Z

Last week, er... no, actually it was this week, I had a bang on the head. Black out, concussion, skull x-rays, the works.

Everything is intact, but my short term memory is temporarily a bit rubbish. My concentration span is minutes at most.

But it has brought into focus something I've been working on for a while - changing my processes to really concentrate on minimising the load on the slowest processor: my brain.

The AS3 application I'm currently building is not a fast-firing game or a web-delivered viral. File size and the speed of event firing aren't a critical success factor, so I'm taking the opportunity to experiment with how I programme, to make it easier for me to do my job as well as I can.

~~Over the next couple of weeks~~ When I get a chance I'll be posting a series of entries on:

1. Using the [robotlegs] framework to cut cognitive boilerplate (it's about thinking, not typing!)

2. Reducing cognitive overhead through ultra-verbose programming.

3. Getting the compiler to pull its weight - including AS3 signals.

4. Using end-to-end testing and the roboteyes tools to get more sleep.

5. Employing project sprouts to make true TDD (unit, integration and end-to-end testing) easier than falling off a log.

The emphasis is on making sure that I can do my job well, and enjoy doing it, even on days when I am much less than my best. Not because I foresee a lot of head injuries in my future, but because as a team leader, business owner, parent, partner and dog owner, there turn out to be a lot of days when I'm interrupted.

I could pretend that all of this is in the interests of my clients. Sure, they benefit. But this new way of working is about the advantages to me today, and the future developers on my project (often also me) - whether that future is 10 minutes, 10 days or 10 months away.

Part 1 coming this weekend.

robotLegs meets as3-signals?

2009-10-20T14:56:00.002+01:00

The flash event model is a bit... sucky.

Robert Penner wrote these 3 blog posts which summarise the limitations:

My Critique of AS3 Events – Part 1

AS3 Events – 7 things I’ve learned from community

My Critique of AS3 Events – Part 2

He's been working on an alternative known as as3-signals, which you'll find on git-hub.

Essentially signals seem to provide the following enhancements: (correct me if I'm wrong here)

A type based rather than string based registration for an event.
Compile time checking that you only register for relevant signals. If SomeClass doesn't have a .clicked signal then you won't be able to listen for it.
Centralised and handy functions for removing all listeners from an event.
The ability to add a listener for one time only (and have it automatically removed).
Useful runtime errors (if you use 'addOnce' after you've already used 'add' or the reverse you get a sensible error).
The option to prioritise listeners - enforcing a calling order.

I'm currently working on this modularised rebuild of an existing piece of complex software. Inter-module communication is the thing I'm thinking about most.

I've also been checking out the interesting stuff over at robotlegs - a DI driven framework which looks light and really focussed... except that Flash CS4 won't let you use the metadata required, so it seems to be Flex only for now.

However, it has a nice command and event mapping model - allowing for type checking, 'one shot only' and so on.

So... I'm considering the benefits of a hybrid. Of creating a command mapped version of as3-signals.

Questions:

1) How to replicate the nice compile time checking that Signals provides while also supporting the decoupling of the modules via the centralised command map - so you can't register for an event that will never exist.

2) Where to put the events? Which package? Do they need to reside in a centralised area?

3) Is this a complete waste of time? Does the command map already provide sufficient decoupling? Should I simply use signals within a module and the command map between modules?

4) Could a module create a new signal 'channel' dynamically, or does that make no sense at all?

Questions... questions...

A framework for Modular AIR Applications

2009-09-16T18:20:00.005+01:00

I've finished building a framework for securely loading signed, packaged swfs into the application sandbox at runtime, while leaving others in the non-application sandbox and rejecting modules without matched signatures.

All the assets, tests, source code and documentation can be downloaded here.

The framework fairly neatly packages the whole process.

The origin of the signature testing process is the Adobe article here, where you can also download a compiled code swc of the necessary flex-only classes if you're working in Flash.

The air application I've built as proof-of-principle achieves the following:

Modules with matching signatures are loaded to the app sandbox (if requested).
Modules without matching signatures requesting app sandbox loading are rejected.
Modules can also be loaded to the non-application sandbox.

It demonstrates:

That app sandbox loaded modules can write to the file system (they put a directory on your desktop).
That non-app sandbox loaded modules are prevented from writing to the file system.
That both app and non-app sandbox loaded modules can pass library assets to the main application to be added to the display list.

It has a lot of user feedback / developer feedback built in. In the absence of the ability to trace in the air application itself I'm listening for this feedback and displaying it in a textarea in the main application.

Currently the information about what to load and how to load it, and where to find the .zip assets on a server to install modules, is all contained in moduleData.xml inside the applicationFlasAndCode folder. When you start the application you must browse to this file.

To use the framework:

Use ModuleXMLLoader to load an xml document containing your module information.
This creates a strongly typed iterator: ModuleDescriptionIterator.
Instantiate ModuleChainLoader, passing it that iterator.
Listen for the ModuleEvent.MODULE_LOADING_COMPLETE event.
Ask the moduleChainLoader to startLoadingModules().
When you handle the loading complete event, run getModuleDictionary().
Access your modules from the ModuleDictionary using getModule() and getSandboxedModule(). You pass the module's unique name to those functions. They pass back the required module.

Any questions at all, post them here or email me.

How secure is secure?

I'm building an enterprise training application. It already exists in AIR, but we're moving to a modular system because our users don't have the permissions required to run the automatic updates.

Secure, for me, is secure enough not to be the preferred target for a malicious attack. Nothing is impossible, but I want to make it sufficiently difficult / tedious that anyone intending to cause trouble looks elsewhere to do it.

Notes:

In my own final application the xml will be a secure data stream coming from a server.

If you want to keep my xml structure you can use the ModuleXMLLoader class as is, but I've kept it as a separate stage in the process so that you can make changes to this.

Some possible gotchas to avoid:

The example module flas have classes which extend ITestableModule. You'll need to point flash to the com folder in order for this interface to be found.
Remember that flash keeps signing with the last certificate you used. So when creating good and bad modules, and compiling the app itself, keep an eye on which certificate you're using.
Module .air packages need to be renamed .zip
You cannot test secure loading in the flash test player. You have to create the application .air file, install it and run it to test it.
Don't forget to grab that SignatureUtils.swc from the Adobe link.

Addition: The flex source files are here.

Creating modular applications in Adobe AIR

2009-09-01T17:48:00.003+01:00

Identity is on hold at the moment, work still being too hectic. I'm hoping to really get down to it next year - I've got 3 O'Reilly books on the way out by March next year, and they're eating all my time.

In the meantime, the main work project I've got going on is a nice fit with what Identity needs to achieve in terms of modularity. It's an e-learning app, already running successfully as an Air application, but we're rebuilding it to achieve the following:

1) Dynamically built modular environment. Other than the AIR shell itself, all the functionality will be loaded by the app at runtime. This allows for non-admin updates, and for user A and user B to have different logging systems / quiz engine etc.

2) Reskinned at runtime. Different departments and sub companies of the corporate client can have a different look and feel, maybe even a different screen size requirement.

I've already grappled with the Air security sandbox stuff within this app. The lessons themselves are dynamically loaded and using sandbox bridge for communication. The current quiz apps are also decoupled, and only simple data is passing around - mostly I'm using strings of xml for more structured data requirements.

I've been playing with the two variations of loading content into flash:

A) The light side: use a normal loader, put your downloaded content into a sandbox where it can only access other content via the safe and secure bridge.

B) The dark side: read the file into a ByteArray and use loadBytes() with allowLoadBytesCodeExecution = true on the loader context, to give your loaded content the run of the place... including the fileSystem.

The pros and cons of breaking the Air security model

The light side:

Events

Events must be passed using loaderInfo.sharedEvents. Only built-in events keep their type, but that's ok. The actual Event.type property is just a plain string anyway, so you can still make use of a custom event for compile time checking to avoid typos, as the Air shell doesn't care that it didn't know what MyCustomEvent.DOG_BARKED was - it just sees "dogBarked". On the down side you can't pass useful extra data with your custom events.

Security

You can use sensible functions like storeAsset(assetPath:String) to pull in things and read / write to the file system, rather than opening up your user's computer for an attack by rogue dynamically loaded modules.

Loading grandchildren

Loading a grandchild asset such as a png or jpg seems to be possible using loadBytes() with code execution set to false. You have to pass the byteArray as a normal array, reconstruct it to be a byteArray, and then load the content in the child module. I've only part tested this. More to follow. And it's pretty gross as a process.

Decoupling logic and events is ok

Modularising the logic of the application doesn't actually seem to be too hard. The code was pretty nicely decoupled already, and we think we can reduce inter-module communication to a combination of vanilla events and xml (passed as string). We'd use the Air shell as a postman to deliver messages from one module to another. There would be an unnerving amount of dynamic stuff which isn't checkable at compile time, but it's doable.

Major hurdle: providing skin assets at runtime

I simply can't find any way to load the actual graphics for the modules at runtime. All I want is to load a specific (dynamically selected) swf with a bunch of MCs in the library, and to be able to do stuff like "new LoginButtonUpSkin()" and whack the requested graphic into the right place. I guess we could export all of our graphics as pngs and use the loadBytes() trick to feed them to the individual modules, but how grim is that?

The other option would be to compile variations on the modules themselves, with different look and feel. "MainMenuGreen.swf" "MainMenuBlue.swf". That feels like a huge pain in the ass when it comes to creating new skins. The designers would need access to the code library, they always ring me up wondering how to link their files to the com folder... you can see the potential headaches I'm sure...

The dark side:

Events: Module to module event traffic is possible. Events don't lose their typing when passing from module to module.

Security: This is dangerous stuff. But all my modules are coming from a trusted server and there's a technique for verifying signatures. Basically any module that wants to be loaded into the application sandbox using the loadBytes() method would have to be an Air app in itself. Then that air package gets loaded and ripped open, the signature verified and the module loaded or rejected. I've no doubt that it's not failsafe.

Will adobe continue to provide this work-around?

The adobe official documentation on working securely with untrusted content end with the following fear-inducing statement:

Note: In a future release of Adobe AIR, this API may change. When that occurs, you may need to recompile content that uses theallowLoadBytesCodeExecution property of the LoaderContext class.

A future release WHEN? What? And will I need to recompile content even if it's happily running. Will Air 2.0 break my 1.5 application if I've used this? Presumably Adobe would provide a better work around for achieving this, but my client doesn't want to do a thousand admin-requiring reinstalls... which is why we're going to use a module based system in the first place...

At the moment I'm still testing, still lurching from favouring one side to the other. More to follow as it unfolds. Hopefully I can save someone the three days of googling and testing I've just been through.

TextMate for Flash, Actionscript 3 and asdoc

2008-09-17T14:27:00.015+01:00

The Flash IDE sucks. I never quite manage to feel at home in the eclipse interface and Flex whines about my Flash components when I try to compile documentation. Powerflasher looks good but resides within eclipse, and FlashDevelop is PC only.

I love TextMate, and I wanted to sort out my workflow so I could edit .as files in TextMate, compile in Flash and also create asdoc documentation for all my code. I read up online and followed a few people's instructions but found I was still a mile away from what I needed. Having worked through those issues, here's a step-by-step guide to getting to a coherent code-document-compile set up with TextMate and Flash.

Note: The paths to put stuff are a good guide, you can alter them if you like later. Create any folders that don't already exist as you go. HD is a substitute for whatever you've named your main Hard Drive. I found that on one of my computers the folder HD/Developer/ was heavily restricted and I had to change the permissions and then apply to enclosed items to give myself write access.

1) Install the Flex 3 SDK (free)

Download from : http://opensource.adobe.com/wiki/display/flexsdk/Download+Flex+3

I downloaded the latest milestone build of the Adobe Flex SDK (not the open source version) but there are also nightly build s available, and stable interim builds too.

Put this folder in : HD/Developer/SDKs/ and then rename the folder to be called Flex.

2) Download and install TextMate (free trial, then $50)

You can get the application file at : http://macromates.com/

A 30 day trial is available, but I'm sure you'll want to buy it. The best $50 I've ever spent on software.

3) Get the TextMate bundles for Actionscript 3, Ant and Flex

You can download the zip files of zipped stable builds from the side bar of creator Simon Gregory's blog: http://blog.simongregory.com/10/textmate-actionscript-3-and-flex-bundles/

The zips are in the right hand column under "Bundles".

To install these, just double click the .tmbundle file once it has unzipped. Textmate will install them in the right place and the file will disappear from your downloads folder.

4) Copy the Flash components .swc files to your SDKs folder

Within HD/Developer/SDKs/ create a folder called AS3.

Copy the Applications/Adobe Flash CS3/Configuration/Components/ folder into this /SDKs/AS3/ folder.

5) Set up your TextMate project.

I keep all my AS3 classes in one top level folder, which also then contains my asdoc building stuff and my docs folder once the documentation is created. You may want to do something different - so feel free to tweak this once you're all set up.

So - my top level folder is /as3_classes/ (this name is not used anywhere so you can call it whatever you like), and it contains my top level packages - com, uk.

Within this folder you should also create the subfolders /asdoc_ant/, /fl/ and /docs/.

In order to be able to work with files which refer to flash components, you need to fill this /fl/ folder with all the fl. package classes.

You'll find these in Applications/Adobe Flash CS3/Configuration/.

There are 4 sets to copy, all of which need to go into that single /fl/ folder in your top level folder. There are two sets of video package files, make sure you add one to the other and don't just overwrite the first. Be certain to copy and not just move these files or your Flash App will go crazy.

Within the /Configuration/ folder above, the 4 fl folders are at:

- /ActionScript 3.0/Classes/
- /Component Source/ActionScript 3.0/FLVPlayback/
- /Component Source/ActionScript 3.0/FLVPlaybackCaptioning/
- /Component Source/ActionScript 3.0/User Interface/

Once you've got them all you should have a list of subfolders like the image on the left.

Now, to create your project, within TextMate do File > New Project. Simply drag your top level folder (the one I called as3_classes, which contains your packages, docs, fl and asdoc_ant) to the folder pane where it says "Drag Files and Folders Here".

6) Create your build.xml file

Within /asdoc_ant/ create a new xml file called build.xml. Paste the following into it:

<project name="asdoc" default="asdocs">
<target name="asdocs">

   <!-- Clean out the contents of the doc directory, without deleting "docs" -->
   <delete includeemptydirs="true">
       <fileset dir="../docs/" includes="**/*" />
   </delete>

   <exec executable='/Developer/SDKs/Flex/bin/asdoc' failonerror="false">
       <arg line='-library-path /Developer/SDKs/Flex/frameworks/libs'/>
       <arg line='-library-path /Developer/SDKs/Flex/frameworks/libs/air'/>
       <arg line='-library-path /Developer/SDKs/AS3/Components'/>
 <arg line='-library-path /Developer/SDKs/Flex/frameworks/locale/en_US'/>

 <!-- these classes are required in your source files in order to use the flash components, but
 we really don't want to have to error check and create documentation for them -->
 <arg line='-exclude-classes fl.accessibility.AccImpl fl.accessibility.ButtonAccImpl fl.accessibility.CheckBoxAccImpl fl.accessibility.ComboBoxAccImpl fl.accessibility.DataGridAccImpl fl.accessibility.LabelButtonAccImpl fl.accessibility.ListAccImpl fl.accessibility.RadioButtonAccImpl fl.accessibility.SelectableListAccImpl fl.accessibility.TileListAccImpl fl.accessibility.UIComponentAccImpl fl.containers.BaseScrollPane fl.containers.ScrollPane fl.containers.UILoader fl.controls.BaseButton fl.controls.Button fl.controls.ButtonLabelPlacement fl.controls.CheckBox fl.controls.ColorPicker fl.controls.ComboBox fl.controls.DataGrid fl.controls.dataGridClasses.DataGridCellEditor fl.controls.dataGridClasses.DataGridColumn fl.controls.dataGridClasses.HeaderRenderer fl.controls.Label fl.controls.LabelButton fl.controls.List fl.controls.listClasses.CellRenderer fl.controls.listClasses.ICellRenderer fl.controls.listClasses.ImageCell fl.controls.listClasses.ListData fl.controls.listClasses.TileListData fl.controls.NumericStepper fl.controls.ProgressBar fl.controls.progressBarClasses.IndeterminateBar fl.controls.ProgressBarDirection fl.controls.ProgressBarMode fl.controls.RadioButton fl.controls.RadioButtonGroup fl.controls.ScrollBar fl.controls.ScrollBarDirection fl.controls.ScrollPolicy fl.controls.SelectableList fl.controls.Slider fl.controls.SliderDirection fl.controls.TextArea fl.controls.TextInput fl.controls.TileList fl.controls.UIScrollBar fl.core.InvalidationType fl.core.UIComponent fl.data.DataProvider fl.data.SimpleCollectionItem fl.data.TileListCollectionItem fl.events.ColorPickerEvent fl.events.ComponentEvent fl.events.DataChangeEvent fl.events.DataChangeType fl.events.DataGridEvent fl.events.DataGridEventReason fl.events.InteractionInputType fl.events.ListEvent fl.events.ScrollEvent fl.events.SliderEvent fl.events.SliderEventClickTarget fl.lang.Locale fl.livepreview.LivePreviewParent fl.managers.FocusManager fl.managers.IFocusManager fl.managers.IFocusManagerComponent fl.managers.IFocusManagerGroup fl.managers.StyleManager fl.motion.Animator fl.motion.BezierEase fl.motion.BezierSegment fl.motion.Color fl.motion.CustomEase fl.motion.easing.Back fl.motion.easing.Bounce fl.motion.easing.Circular fl.motion.easing.Cubic fl.motion.easing.Elastic fl.motion.easing.Exponential fl.motion.easing.Linear fl.motion.easing.Quadratic fl.motion.easing.Quartic fl.motion.easing.Quintic fl.motion.easing.Sine fl.motion.FunctionEase fl.motion.ITween fl.motion.Keyframe fl.motion.MatrixTransformer fl.motion.Motion fl.motion.MotionEvent fl.motion.RotateDirection fl.motion.SimpleEase fl.motion.Source fl.motion.Tweenables fl.transitions.Blinds fl.transitions.easing.Back fl.transitions.easing.Bounce fl.transitions.easing.Elastic fl.transitions.easing.None fl.transitions.easing.Regular fl.transitions.easing.Strong fl.transitions.Fade fl.transitions.Fly fl.transitions.Iris fl.transitions.Photo fl.transitions.PixelDissolve fl.transitions.Rotate fl.transitions.Squeeze fl.transitions.Transition fl.transitions.TransitionManager fl.transitions.Tween fl.transitions.TweenEvent fl.transitions.Wipe fl.transitions.Zoom fl.video.AutoLayoutEvent fl.video.ComponentVersion fl.video.ConnectClient fl.video.ConnectClientNative fl.video.ControlData fl.video.CuePointManager fl.video.CuePointType fl.video.FLVPlayback fl.video.flvplayback_internal fl.video.FPADManager fl.video.INCManager fl.video.IVPEvent fl.video.LayoutEvent fl.video.MetadataEvent fl.video.NCManager fl.video.NCManagerNative fl.video.ParseResults fl.video.QueuedCommand fl.video.ReconnectClient fl.video.SkinErrorEvent fl.video.SMILManager fl.video.SoundEvent fl.video.UIManager fl.video.VideoAlign fl.video.VideoError fl.video.VideoEvent fl.video.VideoPlayer fl.video.VideoPlayerClient fl.video.VideoPlayerState fl.video.VideoProgressEvent fl.video.VideoScaleMode fl.video.VideoState'/>
 <!-- the source of your code to generate docs for - I'm only doing my com folder -->
       <arg line='-doc-sources ../com'/>
 <!-- where the documentation ends up -->
       <arg line='-output ../docs'/>
       <arg line='-templates-path /Developer/SDKs/Flex/asdoc/templates'/>
 <!-- where to look for top level packages - eg the fl package -->
       <arg line='-source-path ../'/>
 <!-- edit this to include your own footer -->
       <arg line='-footer newloop'/>
   </exec>
</target>
</project>

Thanks to many other bloggers I've borrowed sections of that xml from, it was hugely appreciated when I was struggling to get my own version set up.

If you've set up exactly as I've described above then you shouldn't need to edit that file. If you've used other locations then you'll need to edit your file paths to match. It doesn't like paths with spaces in.

You'll notice that the list of excluded classes is pretty long and basically contains all the flash component and base classes, so that you're not compiling documentation on those.

7) Do your FIRST (of many) test documentation build.

These next steps are basically a cycle of building, failing, fixing something, building and failing a bit better and so on until you finally have documentation.

With the build.xml file open in TextMate, press Apple-B to build, or go to bundles > ant > Build.

Most likely you will a list of over 100 errors. It seems to stop and fail at around 115 or so. This doesn't mean that you only have 115, but that it has given up.

Weirdly it then also says "BUILD SUCCESSFUL". This is nonsense - your build did not work. Don't panic, that's totally normal. Some of those errors can be reduced by changing the flex config settings to be less strict. Personally I worked with the least strict config possible until I knew that I could build SOME documentation. Then I reintroduced the strictness and debugged as I went.

To alter the strictness of your flex config open

HD/Developer/SDKs/Flex/frameworks/flex-config.xml in TextMate.

Set the following:

<show-actionscript-warnings>false</show-actionscript-warnings>

<strict>false</strict>

Save the flex-config.xml file.

Build again. Fail again. See the next step for tips for debugging.

8) Fixing your code to get rid of those errors ...

This was a long process, but the types of errors in my classes that I had to sort out may help you on your way:

a) If you have errors like "Error: Type was not found or was not a compile-time constant: TextInput." where you recognise that the type not found is a flash component then check that you've definitely put the flash component swc files in your SDKs folder and the fl files in your top level directory.

b) Historical stuff related to old unit tests / files not now required. Mostly I just binned those. They gave me errors like "Interface not properly implemented" - which is true as I had stopped developing those test files and continued with the interface.

c) Flash Library issues - eg "24 Error: Type was not found or was not a compile-time constant: TestClip.
[exec]
[exec] private var testArea:TestClip;"

Where TestClip was a movieclip inside the library of a Fla, exported with the name "TestClip". You know when the flash IDE says "Don't worry, I'll create this class at runtime ... " well, that's no good for ASDocs.

As tedious as it was, my only option was to create actual classes for all those linked in MCs. And of course I then need to go back to the Fla files and change the export linkage of those symbols in the library to match the final class path. Dull. There may be a way around this but I wasn't able to find one.

d) Issues with 3rd Party frameworks such as Yahoo astra components.

I consistently got the following error:

/Volumes/loopShop/as3_classes/com/yahoo/astra/animation/Animation.as(85): col: 21 Error: Type was not found or was not a compile-time constant: Animation.
[exec]
[exec] var oldAnimation:Animation = Animation.targetsToAnimation[target];

In the end I just dumped from my library the Animation class and everything that depended upon it. Which was OK as I wasn't actually using it. If you are using it then you might have to approach yahoo for a solution - they have their own documentation which must be coping with this error, so perhaps they can help.

e) Issues with Adobe Flash components / core classes.

The only one I found was:

[exec] /Volumes/loopShop/as3_classes/fl/core/UIComponent.as(968): col: 63 Error: Parameter initializer unknown or is not a compile-time constant.
[exec]
[exec] public function invalidate(property:String=InvalidationType.ALL,callLater:Boolean=true):void {

It basically didn't like the use of the InvalidationType.ALL constant. Instead I changed it to "all", which is the value from the InvalidationType class, and it works ok.

You should be able to work through the errors you get, removing classes that are causing problems and aren't needed, fixing pathing issues (I had a few classes where I'd moved them outside their original package accidentally) and creating real class paths for classes which were previously created by flash at runtime.

With any luck your error numbers are reducing, and eventually you get the prize - it generates some documentation in your /docs/ folder!

9) Reinstate some of the compiler strictness

Next you can switch your flex-config back to show warnings:

<show-actionscript-warnings>true</show-actionscript-warnings>

there are a bunch of different things you can warn about, but the really interesting one is this (nearer the bottom):

<warn-no-type-decl>true</warn-no-type-decl>

This one was a real eye opener to me. I had no idea how often I created a variable without specifying a type. I remember probably 90% of the time, but those 10% are a real liability. It created a huge list for me to fix but I think it was worth it as now I can fix them as I go, simply by running my asdoc build before I finish for the day and spotting them regularly.

If you use automatic stage variable declaration in flash then you'll be unable to switch back to strict mode. It will freak out about you using this.myTextField in the middle of a class when myTextField isn't declared as a variable at the top.

So, you need to use:

<strict>false</strict>

If you don't have a bunch of legacy stuff with stage variables being used without being found then you can switch back to strict = true.

When I finally got my docs to compile (a wonderful moment) the ant build also threw a ton of warnings about fl package files that were being excluded and that it couldn't find them. I know I should care about this, but it hasn't caused me any problems so far. My guess is that these are entries in the excluded classes which don't have a corresponding .swc file, but if you've got a better idea let me know.

I have quite a large code library and it takes about four minutes to build my documentation.

10) Edit the ActionScript 3 bundle to use apple-enter to compile your Fla

TextMate top menu > Bundles > Bundle Editor

Unfold the ActionScript 3 bundle on the left.

Click the + button and select "New Command". I called mine "Test in Flash".

Save > All Files in Project
Commands :

echo "document.testMovie();" > /tmp/fc.jsfl
open /tmp/fc.jsfl -a "Applications/Adobe Flash CS3/Adobe Flash CS3.app"

Input > None
Output > Discard
Activation > Key Equivalent (I made mine apple-enter as that's my reflex)
Scope Selector: leave blank

To compile a fla you need to have the fla open in flash. Then from TextMate just press your activation key (apple-enter is mine) and it switches to flash and does the deed.

You can also edit the bundle editor to suit your own for loop style etc. The tab completion stuff is fab.

---

You're all set (hopefully).

Let me know if you have any questions, good luck!

Quick update

2008-09-05T10:41:00.003+01:00

Eek! I've been so slack at keeping this updated. Apologies. My housemate / work partner broke her ankle a few weeks back and life is slightly more complex than usual until she has the use of that leg again - hence no time to really devote to Identity.

Photo evidence is available on my personal house-blog if you're into that sort of thing.

Life resumes (hopefully) on the 25th September when the cast comes off and simple tasks such as carrying a cup of tea to the place where she wants to drink it become possible again.

Still here, and loving TextMate for AS3

2008-07-16T10:49:00.004+01:00

Just a quick note to say that I haven't abandoned Identity and / or fallen under a bus.

The book I'm writing at the moment is in the final intense stages, so spare time is non-existent.

I'll try to reply today to anyone who has emailed me and not heard back.

As an aside - last week I finally completed configuring TextMate to edit all my AS3 projects, and use ant to produce asdocs. I'm mostly working in Flash rather than Flex so it took a bit of wiggling to get the fl. package stuff to stop complaining.

Clearly if you're on Windows then you've got the option of FlashDevelop, but on Mac I've tried Flex, Eclipse with Powerflasher FDT, jEdit, coda (which I'm still using for everything except AS3) and of course the good ol' Flash IDE, but I've finally settled on TextMate and I'm really happy with it.

I'd been using TextMate as a 'power editor' to do extensive find / replace type tasks when refactoring for a while, but had come across multiple problems that stopped me from switching to it for all my AS3 and asdocs.

I'll post a complete run down of how I've finally got it set up next week. Google code group and this blog should be active again from the end of next week onwards.

Aviary invites

2008-06-21T17:17:00.001+01:00

I've got 5 aviary invites to give away.

Let me know if you're interested.

What if Sam releases Saffron?

2008-06-03T15:34:00.003+01:00

I've been asked the question "What happens to Identity if Sam releases Saffron?" a couple of times recently, so I thought it might be a good idea to address it here, as I'm sure more people are wondering it.

The answer is that I don't know (mostly because it won't be up to me). At the moment Sam's website continues to be offline, and all anybody 'knows' about Saffron UML is based on a handful of screenshots and whole bunch of rumours.

If Sam does release Saffron and it turns out to be as good a tool as people are anticipating then either Identity will cease to be something that is worth developing, and we'll just get on with using Saffron (and be glad about it!) or Identity will still look like it delivers something sufficiently different from Saffron to continue working on it. We may even use Saffron for later stages of development, and/or perhaps refactor some of the Identity features to work as Saffron plugins. In any case, the best feature of open source development is the fact that it won't be my decision. If anybody sees value in continuing development then they can go right ahead and do that!

In using the PureMVC framework we're aiming to create some of the functionality we're going to need as add-ons to the framework which should also have use in other projects. We're going to need a set of lightweight components too, and we'll either be using existing open-source code or developing our own for those - which will also continue to have value regardless of what happens with Identity.

I'm personally building Identity because I really want to use it! As someone who used to be a manufacturing engineer I'm also really interested in production processes, and I'm excited about the solutions that we might develop in delivering truly integrated planning / modeling / documentation / stub-code. I've got no urge to be a big name in the flash community, though if Identity does come to fruition I quite fancy the idea of writing a book about joined up processes in AS3. Or something. Probably AS4 by then ;)

Oddly I'm using CRC and UML to structure the book I'm writing at the moment about Global Climate Change. My chapters are like objects, having responsibilities, collaborations, methods and properties. One of the things that I dream about for Identity is the ability to plug-in alternative tools for organising our thinking. Stuff that hasn't been dreamt up yet ...

Snapshots

2008-05-29T15:18:00.005+01:00

Last week I was doing UML diagrams for a colleague to use in building his part of a large application. It occurred to me that the information he actually needed was quite a lot less than what was on the diagram, but as we were doing some test led development, and the model was continuously evolving to reflect the results of our tests, it was too annoying (and unreliable) to have two separate versions of the model to update.

I think the answer to this problem would be for each Identity Project to be able to have multiple 'Snapshots' - as roughly visualised in the pic above. In different Snapshots the state (CRC / Full class element / Collapsed class element) of each element could be different, but making a change to the model would update it overall, and the changes would be reflected in each snapshot.

I've also been thinking about 'visibility filters' for the snapshots. Being able to toggle on and off all public / private / protected / package attributes and operations in the whole diagram would be useful too - I often find myself running 2 copies of a model, one with the entire structure and one to give to a collaborator which only includes the public stuff.

Apologies if this stuff is already present in existing UML tools - at the moment I've decided to not do any research into what's already out there until the first draft of the Identity spec is written up. At that point I think it'd be useful to compare what we've come up with to what's already available, but I'm trying to keep my thinking coming from 'what do we want this to do?' at the moment rather than 'what do other tools do?', knowing that we can pick the status quo up later.

Google code sign-up info

2008-05-23T18:59:00.002+01:00

Join the Identity Modeller project at Google Code here.

I've also resolved the single-core / multi-core puzzle I think. A multi-core version of PureMVC is going to be appropriate for a modules based application whether the app has one or many project windows.

Each module can run its own mini-version of the PureMVC framework.

The recommended strategy for modular PureMVC - presenting an interface to the module - is the only option available within the AIR security model anyway, so the multiCore AS3 port of PureMVC looks like a perfect fit.

I'm hoping that we can develop some of our functionality as PureMVC plug-ins. For example - stuff around history / undo / redo across different modules is going to be a fairly generic solution. The saving of application state (something I love love love about Coda) so that when you start up next time it's just as you left it is also a framework solution that might be of use to other PureMVC users.

I've been thinking about the roadmap and time frame. A couple of people who have expressed interest in being involved are just hitting an intense period of exams and thesis submissions for the next month or so. I think that's potentially a good thing - I believe it takes a while for an idea as complex as this to settle and emerge. My objective then is to remain in planning until the end of June, and work towards a more and more precise definition of the project in that time.

Work begins in earnest at the beginning of July. I'd very much like to get to Alpha in October / November and release the first Beta in time for christmas. Wouldn't that be nice?

PureMVC, and the MDI / TDI quandry.

2008-05-21T09:47:00.004+01:00

CarnageBlood recommended I check out PureMVC as a framework, and I'm really grateful for the suggestion because it looks excellent.

I have no doubt that using PureMVC is a good move - it's opensource and we can develop any generically useful extensions as plug ins that will be useful to other PureMVC users.

The big question I have is single-core or multi-core? How do these relate to interface possibilities?

My favourite applications appear to be a hybrid of TDI and MDI. Coda is an amazing one-window-web-development tool that has tabbed browsing of files open in each window - one window referring to a 'site'. Having multiple windows open means I can entirely separate my work by project / client / server. I love it. Each window has its own interface - file browser, search tool, activity etc. A couple of windows - such as 'clips' - a code snippets tool - are shared across the app as floating panels.

Omnigraffle 5 works in a very similar way. Lots of the interface is wrapped directly around the document, but formatting panels etc are floating shared windows.

I've done plenty of standard MVC development but never a multi-core app. I'm not even sure that what I'm describing is truely multicore? Whilst there would be many models, views and controllers, the actual basis of the application is perhaps still a single core?

More reading to be done - and possibly the best way forward is to plan version 1 as single window (apart from interface floaters) tabbed documents style, with the multiple project windows version as a major update.

Identity modeller roadmap

2008-05-20T20:05:00.003+01:00

If you build it, they will come ...

That's my mantra at the moment anyway. At times I wonder whether I'll get enough active contribution to this project to make it worth doing open source ... and then I tell myself to shut up, because open source is something I believe in. Wikinomics, etc.

I have a genuine passion about this project. I guess it's my old production engineer background coming out - I want to fix the process, regardless of the product. In the last year or so I've begun to feel incredibly frustrated by a lot of the work I do, by the sheer pointlessness of it to be honest. But I still have friends who do OO coding who don't feel able to use UML, or CRC, and I still find I'm having to talk myself into doing it sometimes, and I know that if I had the tool that Identity aims to become I would be a much better coder and technical manager. I know that sharing good code would be easier for starters.

I'm fortunate to be involved in a couple of really, genuinely worthwhile projects - the biggest of which is a training application that runs in AIR. Apart from a really good usable GUI, the AIR-ness means that this app can manage its own updates in a wonderfully smooth way, something which has allowed us to get it out to users much earlier in the process than with a conventional app, where releasing updates might be problematic. We can get a bug report from the client, engineer a fix and release the new update to all users within hours.

Based on that experience, the Identity modeller roadmap aims to release as early as possible. I'm also a fan of getting the risky bits out of the way as early as you can, so we start up with the data side, and work towards graphics at the end. To begin with it won't be pretty, but it will be working.

You can download the roadmap here. (pdf, 1.4 MB)

I've no idea what the timeframe is, which will depend partly on how many people get involved and how their schedules are playing out. If you want to have input into the big picture, in particular the scope of the model and the way data is saved, speak up now. Thanks to all those already chipping in on email and chat!

If you're not able to contribute in terms of coding or design but would like to do unit testing or alpha / beta testing I'm already taking names for those ... don't be shy.

Identity modeller overview documents

2008-05-17T18:38:00.004+01:00

I've gathered together some of the thinking and ideas I've been bouncing around with Jeroen and Weyert, and chucked everything into a 7 page friendly pdf : download it here (1.6MB).

As always, feedback, input, thoughts etc are all very much welcome.

I've also been looking at alternatives to osFlash as they're closed to new submissions it seems. I think probably Google Code is the right choice - if anyone has direct experience of using it please let me know what you'd advise.

I think the next step is a road map of proof-of-principle steps. And later, identifying the bridge API requirements for the various plug-ins and components will be a big exercise - so the more brains the merrier!

Interested in testing or influencing development?

2008-05-07T17:50:00.005+01:00

There are a few different ways in which you could get involved in this project if you're interested.

The easiest is just by reading this blog and chipping in with a few comments here and there.

I'm also going to build some mailing lists, so please drop me an email if you'd like to get involved in any of the following ways:

Top level design team - reading through the specification for the app, contributing brain power to solving the big problems and specifying unit tests.
Coding team - writing classes to unit test for the main app.
Plug-in team - creating swfs to add functionality using the plug-in APIs.
Graphic design team - determining how this thing should look.
Language team - drawing up xml files for AS3 / AS2 etc.
Unit-testing team - testing parts of the app (obviously we'll do as much as possible with automated unit tests, but sometimes you really do need a human to bash things!)
Alpha-testing team - testing the first usable release of the app.
Beta-testing team - does what it says on the tin.

I know this kind of project is potentially a bit daunting, but if you feel like there is a particular task that you'd be interested in, let me know. Maybe you've already got some experience that might be useful - perhaps you're a regex junkie who'd relish the prospect of churning through AS3 files to strip out the data required for reverse generation of models? Or perhaps you're just really good at breaking stuff, and would be an ideal candidate for the unit-testing team :)

Maybe you're up to your neck in actual work but would like to read through the proposals to make sure we're building something that meets your needs as well as our own?

Don't be shy ...

[edit : It's been suggested that we put the project up on osflash.org - a really good idea, but when I tried to do it I found that the sign up page has the following message :

New project signups are currently on hold as we transition to an automatic system. The old manual system just isn’t working out as neither John nor I (Aral) have time to go through the submissions and that’s not fair for you guys.

If anyone has another suggestion please let me know, otherwise I'll stick to the blog for now and set up a svn repository as soon as it's going to be useful. ]

Combining MVC with the AIR sandbox

2008-05-07T11:21:00.006+01:00

Identity seems to be an ideal candidate for the Model-View-Controller design pattern.

I recently converted a large application into an Air app and had to grapple with the differences in how loaded content can access the loader Air file.

There are lengthy and comprehensive white-papers available from Adobe, and they do explain the new model very comprehensively, but I feel quite strongly that the 'What's new in AIR?' overview stuff for flash developers should have had the following simple point:

In order for a loaded swf to be able to communicate with the parent AIR file you must create an API class with public functions within the AIR application and assign this to the loaded swf as a bridge. The only data which can pass between the parent AIR file and the loaded swf is simple type data : Number, String, Boolean. You cannot pass complex typed data between a loaded swf and a parent AIR file.

The implementation of this into our application was initially a bit painful. The application is a training environment. The main AIR app loads external swfs of individual lessons and quizzes. The app GUI has all the interface and the loaded swfs basically only contain a timeline with a voice over and animations and a small amount of functionality. There is quite a lot of communication between the two however - with the loaded swf prompting the GUI to update all sorts of things - messages on screen, navigation state, icons indicating the availability of other resources.

We had previously achieved a lot of decoupling by using events. In the new model it was no longer possible for a typed object, such as an event, to pass between the swf and the AIR app. Of course it took a whole bunch of testing and digging through various white-papers to realise that this was the issue ... but we got there in the end.

The result is an even more cleanly decoupled app, with less requirement for the animators to put code into their lessons, and the AIR app is at far less risk of being broken by anything they do. At the moment there is a small loss in compile-time error checking, though I suppose we could define constants within the local lesson to get back what we had with the events.

So - I am thinking about what the AIR security sandbox will mean for Identity.

It makes sense to have a number of the core functions held in separately compiled swfs, so that they can be extended / swapped easily. This also gives a lot of protection to the core application as it means that only expected data can pass through. We can check and place limits on this data before it is used within the app. Lovely.

For example - the ECMAScript-based parser should be able to handle AS2, AS3, AS4 and probably PHP5 and 6, but I haven't a clue what other languages people might find this useful for. The logic for creating / stripping an AS3 file is quite clear to me - you need a file that defines how a class is built and then you do some regexy things and some iteration through the properties and functions. How universal that logic is I don't know. How much customisation you can do without editing the parser, I don't know. How much benefit coders might get out of editing the parser to suit a specific need, I don't know. So - if the parser is an externally loaded swf then you can select a parser to use and introduce a layer of flexibility. You can even build your own. People can experiment easily with their parser and make public 'improved' ones maybe.

[I'd love to see a parser that simultaneously builds your asDoc html, for example ... not sure how this would be possible right now, but it doesn't feel completely unrealistic, if the parser simply called file writing functionality within the API].

You can assign a specific API to each loaded swf, but you can only assign one. So, that API needs to deal with all relevant aspects of Model, View and Controller in one class, though of course it's just a gateway through which simple-typed data passes.

Application-sandbox loaded components do have a lot more potential for interaction with the parent AIR app, but I think the outside-the-app model offers a much more secure and controlled environment for plug-ins, so this seems like the best route. Identifying the kinds of functionality each of the plug-in API classes needs to have is a pretty big task in itself ... doing the planning for this project is making me more certain that I need this piece of software though!

(For mac users, if you don't already have it then you should check out Omnigraffle Pro 5 - the best piece of software I've ever used just got a whole load better.)

Project language spaces & class interchange

2008-05-05T20:30:00.002+01:00

I'm definitely hooked on the idea of being able to model once and export stub code in multiple languages.

The potential benefits in terms of providing shared 'Class swatches' are pretty attractive.

So far what I'm imagining is that when you start a new project you select a language space for that project. You would then be able to drag previously defined classes from a classes swatch thingy (best to be specific about the lack of definition here!) into that project - and the app would translate unsupported types according to the type mapping spec for that language. Swatch classes would only be able to be edited within the language space they were defined in - so you couldn't start adding MovieClip types to a class which you've created in ECMAScript.

You would also be able to create a new class 'based on' an existing class in your class swatches - this would import the class types into your project language and allow editing within that language.

Making sense?

Introducing identity modeller

2008-05-05T15:21:00.005+01:00

Dauntless pointed out on email that I can't keep calling it "Air UML tool thing" ... and I thought coming up with a half-decent name would take ages, but here I am already, introducing Identity modeller. Whadya think?

I wanted it to convey the fact that the code and the model are intended to stay in step with each other ... and 'congruent' isn't exactly catchy.

Plus, like all good math-geeks, I'm a long term fan of Euler. Couldn't resist ... sorry!

Air UML Tool : File formats and more on typing

2008-05-04T20:21:00.006+01:00

I've been trying to wrap my head around the xmi specification for describing UML models using xml. The purpose of the spec is obviously to allow models to be imported / exported and switched between different UML tools.

It has given me a focus for the core functionality of the application - to be able to read and write both xmi models and language specific class files. The application would then also have the ability to write extended xmi files, containing the compliant xmi model stuff but also the project data relating to everything else - non uml stuff to do with getter/setters, positioning, etc etc.

The language specific element will be provided by external xml configs - one to describe how a class file is structured, and one to map generic types to language specific types.

I've been having a bit of useful exchange with Dauntless on the types issue. The thinking I have at the moment is that some classes are clearly language specific - anything using or extending MovieClip for example is only useful in Actionscript - whilst other classes might be much more generic, in which case it would be nice to be able to move them across different language projects. I have a few utility type classes which I use in both AS3 and php5.

The most basic type set is that provided by UML itself: boolean, integer, float and string.

Then there is the set provided by ECMAScript 4 - discussed in the previous post.

As Dauntless pointed out, Java has useful stuff like Enum.

I think I've almost reached a clear enough understanding of the multiple-languages issues to be able to post more detail of that tomorrow.

As always - the more the merrier - please chip in if you're interested in contributing.

Meantime - if anyone can think of a good name for this baby ... Dauntless has rightly pointed out that AIR UML Tool is getting a bit dull ...!

AIR UML tool : Working with types across different languages

2008-05-02T19:37:00.006+01:00

One of the most obvious changes when switching between AS2 and AS3 is the difference in built-in types.

I'm talking Number vs int / uint. Void vs void.

From time to time I plan something that I want to execute in more than one language - in php5 or Actionscript 3 ... I've been fortunate to be able to leave AS2 behind but I know a lot of people are working on legacy projects.

With Colin Moock already talking about Actionscript 4, the focus for future-proofing seems to be on ECMAScript 4.

The release data for the new spec isn't til December 2008, but I'm guessing the end of the year will be upon us in no time.

Reading through the ECMAScript 4 Overview, it's struck me that building with this spec in mind will force us to include the kind of flexibility that will make it easier to extend this app to other languages.

For example - some of the Number types proposed - byte, int, uint, double and decimal - may not make it into the final spec, and we may continue to have the current AS3 set: int, uint and Number.

If each language contains a type mapping spec for the core types then AS3 can map byte, double and decimal to Number, and if AS4 supports them then they can be supported.

eg:

translations/as2/typeMapping.xml :


<typeMapping>
<type_byte>Number</type_byte>
<type_int>int</type_int>
<type_uint>uint</type_uint>
<type_double>double</type_double>
<type_decimal>decimal</type_decimal>
<type_Number>Number</type_Number>
</typeMapping>

translations/as3/typeMapping.xml :


<typeMapping>
<type_byte>uint</type_byte>
<type_int>int</type_int>
<type_uint>uint</type_uint>
<type_double>Number</type_double>
<type_decimal>Number</type_decimal>
<type_Number>Number</type_Number>
</typeMapping>

translations/as4/typeMapping.xml :


<typeMapping>
<type_byte>byte</type_byte>
<type_int>int</type_int>
<type_uint>uint</type_uint>
<type_double>double</type_double>
<type_decimal>decimal</type_decimal>
<type_Number>Number</type_Number>
</typeMapping>

So far, the types I can identify in the ECMAScript 4 list are:

null, undefined, void

Object

Number, byte, int, uint, double, decimal

Boolean, boolean

String, string

Array

Vector (a strictly typed array?)

Function

Map (binary relations)

Date

RegExp

Name, Namespace, NamespaceSet, NamespaceSetList

Error, EncodingError, EvalError, RangeError, ReferenceError, SyntaxError, TypeError, UndefinedError, URIError

AnyString = (string,String)
AnyBoolean = (boolean,Boolean)
AnyNumber = (byte,int,uint,double,decimal,Number)
FloatNumber = (double,decimal)

XML, XMLList, AttributeName, AnyName

IterableType, IteratorType

I've also spotted a few more in the documentation - FieldIterator and ControlInspector perhaps?

Either way - this strategy allows us to be highly specific in our documentation, and then water that precision down for each language. Of course, coming back the other way it's trickier. Do we want reverse engineering to simply pick the most generic type, or do we need a special comment that can specify how types are backward translated? Something like ... (for AS3)

// *strictType:decimal //
public var salary:Number;

Obviously the app also needs to support types from your own library.

Something else I've noticed is the support for ! ? notation to specify that an object can / can't be null. Eg

// "!" indicates that v can't be assigned null
var v : MyType!

// "?" indicates that v can be assigned null
var v : MyType?

// "!" indicates that this whole class is non-nullable
class MyClass! { ...

The idea is that this will allow earlier detection of null-pointer errors - ideally at compile-time rather than run-time. That would make me very very happy!

----

It's a pain that ECMAScript 4 is still six and a bit months from completion, but I think the rigour that having to build for an almost-complete standard gives us is probably a good thing.

AIR UML Tool : Defining the UML scope

2008-05-01T19:16:00.005+01:00

UML 2.0 is pretty vast.

This is an attempt to summarise the parts of the UML that need to be available within the tool. My current thinking is that different languages will have an xml spec file that maps these UML Language elements to the translated element for that language. We should begin with AS3 as a primary goal, but ensure we support parts of the UML which aren't yet available to actionscript but might be included in PHP6 or AS4.

For example - AS3 doesn't support 'private' or 'protected' on a constructor, so the AS3 xml config might map it to 'public' in this case. AS3 also doesn't support 'abstract', so that would be skipped when constructing the stub AS3 code.

The list below is probably incomplete but it's a really good place to begin. Strict UML terms are given in (brackets).

Stuff

package
class
interface
property
function (operation)

Visibility

public
protected
private
internal (package)

Scope / implementation modifiers

static
abstract (unsupported in AS3 but we can hope and at least add to comments)
const (readOnly)
binds
dynamic (not sure this has a strict UML equivalent?)
overrides [thanks dauntless]
final [thanks dauntless]

Class relationships

extends (generalizes)
implements (realizes)

Any glaring errors? If you're out there following this and it makes sense to you please do speak up, encouragement, questions, interrogation and the pointing out of obvious fundamental flaws are all appreciated.

[edit]: Dauntless has also mentioned composition, which is definitely required within the laying out of diagrams / relationships, but doesn't really map to an AS3 file other than by declaring a property of that type - or am I missing something?

We'll also need to represent the Aggregation / one-to-many : many-to-many : many-to-one type relationships as well, and also event listener lollipop etc, but again I don't think they map into the final exported AS3 files.

Dauntless also brought up the issue of types - something I've been thinking a lot about and hope to post some ideas for a strategy later today.

AIR UML tool : A clearer concept

2008-05-01T18:38:00.009+01:00

To save any confusion - this is just a graphic, a jpg exported from a flash file which has absolutely no functionality and is purely intended to help rough out an interface concept.

I started thinking in more depth about what I personally needed this tool to be able to do, given that I'm pretty happy with my current working strategy but it just feels like there's a fair bit of friction in the system in terms of duplicating work.

So, I went right back to basics - my current process, which I'm sure is not unique, is to use index file cards for a fair bit of my modeling. On one side I scribble the CRC stuff (Class Responsibilities and Collaborations). On the other I outline the most important public properties and functions.

At a later stage I do a more formal UML diagram in Omnigraffle, using the UML-General template. Then, once I'm satisfied that it's close enough to what I'll finally need, I create skeleton AS3 classes in Flash or Flex, and then write in skeleton asDoc comments ... both of which are rather tedious.

Inevitably the coding process throws up unforeseen stuff and functions, structure or even the whole model can be subject to changes. Unless I am feeling particularly disciplined, many of these changes go mostly undocumented, usually only being written up if the code is then applied to a new project or handed over to a new developer.

I no longer work as part of a large team of developers, so I've only my own experience to call upon, but if there's one thing I've learned in my time as an engineer (in both the physical and the software world) it is to begin by making a product that a single concrete person needs, and not a product that doesn't actually satisfactorily meet the needs of any of a whole bunch of abstract people :)

Where I've landed is that this tool should be like a digital version of my index file card box, which integrates my workflow all the way through from creating CRCs to assembling them into a project, to defining public interfaces on the flip side, to drawing that up in a UML sketching tool, to defining private functionality, to adding comments to explain usage, to generating AS3 skeleton functions with asDoc compatible comments and getter / setter functions where desired ... it has to take care of that whole shebang.

That process has to be 2 way, preferably with 'intelligent' (the magic word for 'haven't defined the rules for this yet') syncing.

Returning to my dodgy graphic at the top - I'm no designer, so will be looking to get some major input on that side - the concept is that you have a bunch of index cards on screen, you click the little arrow in the top right corner to flip 'em round. They expand and contract to give enough space for the properties / functions. All the standard spec of UML 2 is available to you and they also have a neat interface (represented by the G S on the right of the properties) for requesting that Getter / Setter functions be created for those properties.

I'm sure there will be other, sexier, less geeky skins that people want to add later but this one seems like a great one to kick off with because it focusses the mind on what we're trying to do - take the friction out of a tried-and-tested way of working, not revolutionise the whole process!

AIR UML thingy overview

2008-04-08T15:23:00.004+01:00

So ... here's the overview of the project.

The green box contains the most basic possible release of the software - no real whistles and bells beyond getting something useful that we can start using / testing.

The boxes above that are the language / saved file format stuff.

The blue boxes are things for versions 2 to 100 ...

All saved data / parameters / language specs etc will be in xml. The entire app will be written in AS3 only - nothing specific to Flex or Flash. No assets ... well, maybe a png library later, but it should be possible to compile the project from either an empty FLA or a simple Flex project without requiring any assets.

So - with the whole project written in pure AS3, anyone who uses the software will also be able to modify / adapt / enhance / reskin it.

In terms of UML elements, I think we should start with the most commonly used elements and then add further ones later.

As far as interface / usability goes, my 2 favourite pieces of software are coda, by panic, and omnigraffle by omnigroup. If we get anywhere near to something as beautifully usable as those two I'll be a very very happy bunny.

The 'class swatches' add on is something I'm kind of excited about myself. It would allow you to have templates for classes / design patterns that you drop in and edit.

I'll expand more on the diagram above as soon as I get a chance, and it's by no means a concrete solution, just the one that I've come to so far - all feedback / ideas gratefully received.

Open-source Saffron-like UML tool

2008-04-04T12:07:00.000+01:00

Saffron is / was an AIR-based UML tool that promised great things, but so far has yet to deliver even an Alpha.

Like many others I've binned my own UML tool project believing that Saffron was just around the corner and far exceeded my own project's limited capabilities.

The AS3 community's response to Saffron has been overwhelming - we want this tool. Badly.

Whatever the reasons for Sam's non-delivery on Saffron - and frankly it's not like he owes us as all we've invested is our hope - I’ve given up on Saffron appearing anytime soon.

Leaving behind the rumours, Saffron would be a fantastic tool and Sam has clearly solved a few of the usability issues that bug me about other UML tools. Whether or not he has been able to execute it, his concept is seriously good.

If a bunch of us got together I believe we could do this open-source quite rapidly. If there is interest I’m prepared to get the ball rolling - if we all want Saffron so badly then we need to deliver it ourselves!

I am looking to gather together contributors to work on the project, taking this (scaled down) vision as a starting point:

Project scope:

The tool will run on AIR in multiple windows.
It will allow you to generate AS3 stub code + asdoc comments from your diagrams.
It will allow you to generate diagrams from AS3 code (with asdoc comments).
It will allow you to add additional commenting to classes / functions.
It will stick as closely to UML 2 as is feasible and support the core OO concepts.
The API will be built with expansion for other languages in mind - all they would require is a new parser logic.
There will be autocomplete / prompting for classes already included in the project diagram.
Data / projects / configs will be held in XML files.

Ethos

There will be a focus on releasing usable builds as early and as often as possible - even if they are ugly! Provided we maintain backward compatibility it's more valuable to have a tool that helps us do some of what we need than nothing.
All project components / specs etc will be open-source and public.
All development will be test driven - tests written before code.
Refactoring will be encouraged.
No effort is too small - write just one class that solidly delivers and passes its unit test and your contribution is valuable.
The project will be cross platform Flex / Flash to maximise the number of possible participants. (Yes, it's a pain, but I think it's worth it).

If you're interested please say so below ... with the right approach and the right numbers of people this thing could fly quite quickly, don't you think?