PureMVC, amendments to best practices

I recently inherited a very well written PureMVC project, following the recommended best practices to the letter - and it gave me a lot of headaches. So I'm making some amendments.

First let me give some context. This project was a video player project, the client orginally had their own in house video player, (ie NetStream based), but are now moving to a service for their videos. They wanted to keep the UI the same, just switch out the video player.

This is perfect, this is exactly what an MVC framework should be about, I could keep the view part and just replace the video player and model to where the data was coming from.

While trying to decode the source code, I started by just seeing if I could instantiate just one of the mediators, to see what the view looked like. Compiler Error.

Turns out, that the mediator had referenes to the ApplicationFacade to get the notification names. Well that means that the entire ApplicationFacade had to be compiled. That meant that all of the registered commands, mediators and proxies, had to be compiled. So somewhere deep within the framework, I was missing a bunch of classes.

So my first step was to comment out all of the proxies and commands, as I only wanted the views. Still no joy. Not wanting to remap all of the notifcation declarations, I made a MediatorNameConstants. This file had a list of all of the mediator names, but without references to the mediator classes. I updated all of the NAME values of all of the mediators to point to this file as well as all of the references.

Now when I wanted a mediator, I only needed that mediator and the facade, not all of the framework.

As I worked through the code and added stuff back in here is the list of best practices regarding PureMVC that I came up with.

• While tedious, keep all mediator and proxy names in a separate constants file.
  I did this so any mediators or proxies that were referenced in mediators, weren't required to be compiled in, only their names.
  
• Then within a mediator, command, or proxy, instead of creating local variables for other mediators or proxies, declare them as explicit getters
  Like this:
  public function get myProxy():IMyProxy { return facade.retrieveProxy(MyProxyConstants.NAME) as IMyProxy) }
  
  That way the class can be overwritten for extension and testing. This would also allow for some dependancy injection, if so desired.
  
• Make the proxies into interfaces, at least the major ones, like ApplicationProxy or ConfiguationProxy.
  Now there is a theory that says if you only have one, than an interface isn't needed, and I agree. Although I think for something that is major and widespread like the two mentioned above, that an interface of one does make sense.

If these things were in place in my inherited project, it would have saved me days worth of debugging and code searching efforts. 

Any color "sepia" using Adobe PixelBender

I wanted to entitle this as "Personally proud moments in programming", but I didn't think that I would get any traffic on it. But this is one of my most proud discoveries.

About 4 years ago, I was on a project where the requirement was to custom tint photographs. The client wanted not only sepia tone, but many different colors, like yellow or green.

Many of the pathways that I tried resulted in images that would look ok only if they didn't have the target color, but if they had green, for example, they would blow out and be just awful looking.

Now, I know what you are thinking, why was this hard, convert to greyscale and then add a transparent overlay and you should be good to go... wrong... it looked awful. Try it, you'll see... awful.

Then I discovered the YIQ color space. This is the color space used by original television broadcasting to get to black and white TV. This was perfect because once it was black and white it was easy to add the color.


So I found this formula (sorry to whomever I originally found it from, but I found it again, it WAS 4 years ago). I copied the code out of the link so you don't have to follow it, but I wanted to give credit to *somebody*

RGB to/from YIQ

The YIQ system is the colour primary system adopted by NTSC for colour television broadcasting. The YIQ color solid is formed by a linear transformation of the RGB cube. Its purpose is to exploit certain characteristics of the human visual system to maximize the use of a fixed bandwidth. The transform maxtrix is as follows

Y I Q

=

0.299 0.587 0.114 0.596 -0.274 -0.322 0.212 -0.523 0.311

R G B

Note: First line Y = (0.299, 0.587, 0.144) (R,G,B) also gives pure B&W translation for RGB. The inverse transformation matrix that converts YIQ to RGB is

R G B

=

1.0 0.956 0.621 1.0 -0.272 -0.647 1.0 -1.105 1.702

Y I Q

So what this looks like in pixel bender is:

kernel colorSepia
<   namespace : "com.squaredi.colorutils";
    vendor : "Drew Shefman";
    version : 2;
    description : "a variable color sepia filter"; >
{
    parameter float intensity;
    parameter float destColor
    <
        minValue:-2.0;
        maxValue:2.0;
        defaultValue:0.0;
    >;

    input image4 src;
    output float4 dst;

    // evaluatePixel(): The function of the filter that actually does the 
    //                  processing of the image.  This function is called once 
    //                  for each pixel of the output image.
    void
    evaluatePixel()
    {
        // temporary variables to hold the colors.
        float4 rgbaColor;
        float4 yiqaColor;

        // The language implements matrices in column major order.  This means
        // that mathematically, the transform will look like the following:
        // |Y|   |0.299     0.587   0.114   0.0| |R|
        // |I| = |0.596     -0.275  -0.321  0.0| |G|
        // |Q|   |0.212     -0.523  0.311   0.0| |B|
        // |A|   |0.0       0.0     0.0     1.0| |A|
        float4x4 YIQMatrix = float4x4(
            0.299,  0.596,  0.212, 0.000,
            0.587, -0.275, -0.523, 0.000,
            0.114, -0.321,  0.311, 0.000,
            0.000,  0.000,  0.000, 1.000
        );
        
        // Similar to the above matrix, the matrix is in column order.  Thus, 
        // the transform will look like the following:
        // |R|   |1.0   0.956   0.621   0.0| |Y|
        // |G| = |1.0   -0.272  -0.647  0.0| |I|
        // |B|   |1.0   -1.11   1.70    0.0| |Q|
        // |A|   |0.0   0.0     0.0     1.0| |A|
        float4x4 inverseYIQ = float4x4(
            1.0,    1.0,    1.0,    0.0,
            0.956, -0.272, -1.10,  0.0,
            0.621, -0.647,  1.70,   0.0,
            0.0,    0.0,    0.0,    1.0
        );

        // get the pixel value at our current location
        rgbaColor = sampleNearest(src, outCoord());

        yiqaColor = YIQMatrix * rgbaColor;

        // Here we set the I value of the YIQ color to the intensity
        // specified in the UI.  
        yiqaColor.y = intensity; 
        // zero out the Q to apply the sepia tone
        yiqaColor.z = destColor;

        // convert back to RGBA and set the output value to the modified color.
        dst = inverseYIQ * yiqaColor;
    }
}

Which in using can give you images like this:

 

Original

 

DestColor = -0.16

DestColor = -0.24

DestColor = -0.3

Not bad, eh? (That's me, publicly patting myself on the back :) from 4 years ago )

Refactoring Responsibly - 360Flex Preso

Here is the slide deck (pptx) from my 360Flex refactoring preso.... Refactoring Responsibly

If you want to see the embedded version without the cool animations:



There we also some questions that I'll do my best to remember and try to answer again.

Q: Did you come up with the "First Draft" idea for coding / programming?
A: As far as I can tell, I couldn't find any other references to it on my searches. It was an idea that developed as a result of trying to sell upper management on the idea that we needed to refactor.

Q: What about refactoring to improve performance?
A: Performance is a whole different animal. If you are looking to get major performance gains, you might need to do more re-writing than cleaning up. You will probably want functional tests to be your characterization tests. And yes, the characterization tests add more function calls, which will probably cause *some mild* performance degradation. But then the choice is readable maintainable code, or performant code. Usually these things are orthogonal. As a side note, once you have tests in place, you have an open field with high confidence of what you can do. If you redesign, get better performance, and the tests still pass, then awesome. (And if you do redesign and the tests still pass, welcome to test driven design :) it is a great thing)

Q: What if I come back and do my second draft the next day, do I still need tests?
A: You are testing your code in some way. Whether it is manually executing the actions or running automated tests. If you write your 2nd draft the next day, that is a different level of refactoring then I'm talking about. I'd call that a good idea on the code that you were creating. You aren't in production yet, you are adding a feature or fixing a bug.... you are still developing and while working on the problem, you thought of a better way to do it. Clearly however you verified that your code worked yesterday is still clear in your mind, and you can easily verify that it works today. I'm a TDD and automated test advocate, so I'd say yes you need tests, but if that is not part of your philosophy, then it is up to you to decide the maintainability of your code

Q: Doesn't refactoring admit that you screwed up the first time.
A: NO! As the Refactoring Prime Directive states : "Regardless of what we discover, we understand and truly believe that everyone did the best job they could, given what they knew at the time, their skills and abilities, the resources available, and the situation at hand. "

Q: Could you slow down next time?
A: I certainly will ;)

You've got an ugly baby: How to "sell" refactoring

Look, nobody likes to be told that they have an ugly baby.

If you are new to an existing corporate project, you are fairly likely to find a code base that could use some improvement.

If you happen to be fortunate enough to have the project manager tell you that they have amassed significant technical debt and need to work on reducing it, then you don't need to read the rest of this post. Attend my 360Flex presentation or check back here for my slide deck in a couple of weeks to learn how to refactor responsibly.

But for the rest of us, telling the client that the code base is not usable and needs to be massively cleaned up, is like telling a parent that they have an ugly baby. They won't hear you.

I've tried using the reduces maintenance costs / increases bug fixing time arguments too. And frankly, when faced with a looming deadline, some clients have outright said "I don't care about maintenance."

Now I disagree. If you are working on a marketing campaign that has an expected 3-4 week life.... fine. Get 'er done and life is good. But when you are working on a project that has an expected life of years, or even in this case a decade or more... then it is insanely short sighted to not care about maintenance.

Clearly, timing is important... Don't propose an immediate refactoring initiative a month before a major deadline. Do however propose it for immediately after the deadline.  From my experience, if you are not "agile", then your deadline is a major milestone... maybe even a release. This could mean that there will be a period of QA testing, acceptance testing, approvals, etc. For us, this was a time that the developers were supposed to work on documentation, as the code was "frozen". (I disagree with both of these statements).

This is the perfect time to refactor. If you need to "document" your code, then you need to refactor. Well written code is self documented. I'd also argue that writing unit tests are the best form of documentation that you can have.

But I digress, this post isn't intended to be about refactoring, it is intended to be how to talk about refactoring so that business will listen.

If you find that concepts like refactoring, technical debt, or maintainability are not working for you in terms of buisness buy-in, we've had some success with some others.

• "Future BIG IDEA" enablement

For us, it was the "new backend framework enablement initiative". This "sold" incredibly well. We were granted a 5 week sprint for enablement (refactoring)

It was during this "enablement" sprint, that this next idea really proved itself.

• Training / ownership

In my case, I'm a consultant. I have two main responsibilities: Help the team with some new code, and train the (soon to be maintenance) team. During the refactoring iteration, the team learned more about their code then I could ever deliver myself. No matter how many presentations, diagrams, code reviews, etc. I gave, nothing would compare to getting the team to improve their own (team's) code.


As a developer, refactoring is wonderful!

1. The requirements are perfectly clear (do exactly what it is already doing). 
2. The end state is self defined (I can stop refactoring at any time that I've made any level of improvement, assuming that nothing has changed).
3. Identifying what  to change is clearly describable to any level developer ( code smells )  

Actually, the results of this sprint were amazing! And I'm obviously not talking about functionality, as true to our intent -- nothing changed. But now, the transformation in the team was astonishing.

• Junior developers had dozens of light bulbs / ah - ha moments regarding their own and future coding standards. 
• Everyone felt responsibility and ownership in the code base, which previously was more a lay blame / obligation. (see responsibility model )
• We all had fun. It was unanimously voted the" best time" in all of the project's duration
• The team of developers had transformed into the "team" (performing, in the Tuckman's_stages_of_group_development)

So if you need it... it is no longer "we need to rewrite this code". 

Let, "we need to increase team ownership by enabling [The next big thing], before we start the next phase." -- be your next refactoring battle cry.

  

Refactoring and Respecting the Team

So I'm working on my 360Flex presentation and I realized that there was a very important lesson that I've learned about refactoring and team respect that is unlikely to make it into the actual presentation.

So if you are not going to read the whole backstory coming up... here is the quote from the retrospective prime directive that illustrates my point perfectly:

“Regardless of what we discover, we understand and truly believe that everyone did the best job they could, given what they knew at the time, their skills and abilities, the resources available, and the situation at hand.”

And now for the back story.

A couple of years ago, I was brought onto a team as a senior flex developer. One of my first tasks was to mentor the team in best practices. The novice flex team had been writing flex code on their application for about 6 months and, as might be expected, there were lots of areas for improvements.

But there was one section of code that I came across, which absolutely blew me away. I couldn't believe how bad this code was.

There was a view component that created an alert. Within the alert callback, within the same view component was a switch statement. This switch statement evaluated the width(!) of the alert to determine the business logic of what should happen next.

It looked something like this:

switch(alert.width)
{
    case 341:
       //do approval workflow
       break;
    case 354:
       //do normal workflow
       break;
    case 362:
        //do cancel workflow
       break;
}

As I said... I was completely flabbergasted. I couldn't imagine how anyone, novice or not, with any coding experience, in any language, could think that this was a good idea. Didn't they realize that width's are arbitrary and volatile?! And this was critical business logic, nevermind that it was contained in the view, but business logic based on width!

Clearly this still agitates me.

So I created my best-practices presentation, with this code as my shining example of bad code and the need to refactor. I was feeling particularly proud of myself and how much value I would be adding to the team, as if to say -- if this is the code that they were writing, I could bring them up many many levels.

So I showcased this example, hand waving madly why this was so bad. Nearly immediately, the technical architect / my mentor / team lead, stood up and proclaimed that this was his code.  My first thought was "clearly this isn't his code, this is the code of a total..... oh *$#^&, someone in *this* room wrote this code that I'm totally tearing apart."

So after lots of backpedaling, apologizing, focusing on better ways of organizing the code in general, and blaming the tech architect for such bad code <wink>, the presentation was favorably received.

But, boy, was that a slap in the face for me... and certainly a lesson that I'm not going to forget nor repeat.

It wasn't until just a couple of weeks ago that I found the above retrospective prime directive, but it perfectly sums up the philosophy that was thrust upon me in that moment.

That moment that completely altered my course.
That moment of supporting the *team* first.
That moment of respect.

Programming Persona and Programming Practice

I ran across these two posts today, and they totally nailed both the programmer's pardox and programming practicing:

https://sites.google.com/site/steveyegge2/being-the-averagest

https://sites.google.com/site/steveyegge2/practicing-programming

StageText and SkinnablePopupContainer

After much head scratching, I discovered that on the mobile AIR SDK, that TextInput wraps StageText. This is cool, because we can use native keyboard handling. But you have to watch out, if you create a popup, you could have your stage text on top of your popup. The solution - ensure that all popups extend SkinnablePopupContainer, and life is easy. Of course this is what Adobe recommends, but to my knowledge they didn't say why. :)

If you are creating custom popups and/or using external libraries make sure you can verify the object hierarchy and that SkinnablePopupContainer is there.

I write this because I found a mobile UI library that I was playing with and it didn't, and I had to spend time debugging. Since the search results did not provide and obvious solution, hopefully this post helps someone else if they come across the issue where the TextInput is always on top regardless of the z-order depth.