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.  

TDD is like losing-weight-hard & fails with converging prototypes

First off, I'm trying to develop better TDD habits, and changing habits is hard.

It is very related to losing weight. It is easy to get to the gym / eat less for a week or two and you are feeling great. You are a losing-weight-TDD rockstar. Then you hit that stressful moment(s) and all of a sudden you are back to old habits. But you are think that as soon as the stress passes, you'll get back to the gym / do some TAD (Test After Development), except that it is way harder to get started again.

I've also come to realize that there are times when TDD is very appropriate and times when it is not.
TDD is a lifesaver when you have clearly defined goals / user stories. You write your test to meet the acceptance criteria, write your class, and you are golden.

But when your goals are nebulous, like the client's core reason for a project keeps getting redefined, then TDD gets in the way. If I were to name this, I'd call this  "converging prototype" development. This is where they don't really know what they want, nor even the specific business problem they are trying to solve. They have a general pain point, or new idea, but it isn't flushed out (that is your, the developer's job). This is where you have a just in time backlog, and you are working on 1 week iterations. At the demo at the end of each week, the current application / prototype is really a "conversation starter" rather than a releasable item. Here is where TDD is not useful, as there is no goal. What are you testing?

Sure you could write tests for what you had, but at the moment it is still a prototype, or proof of concept. Core ideas are still highly vulnerable to massive changes. And designing / developing / AND testing in this phase sucks.

At some point, 3-4 iterations later, it is likely (hopefully), starting to converge on ideas / workflows / datatypes (yes, even datatypes couldn't be well defined initially). So now that we are converging, now is a good time to do some TAD.

Given it is not ideal, but testing after at least gets you tests, which is way better than no tests.
 This is also a good time to clean up / redesign where you are converging. Notice that I didn't say refactor, we are not necessarily trying to retain all of the functionality. We are still talking about a prototype.

We know that in another iteration or two, this prototype is going to cross over to be the actual app, but for now, we can be a little bit flexible with the "requirements".

In my commitment to more TDD, I've found that it is project specific goal. On my well defined project, I have 100% TDD and I LOVED it. On my poorly defined project, I started with about 80% TDD, and rapidly  dropped to 0%. The project has had 3 major direction changes, and the tests and codebase were nearly 100% irrelevant after each change.

I guess my next discovery is how well I write testable code without tests :)

Spark Data Grid - Precision Focus Control - preso

So I'm re-presenting my Spark data grid presentation that I did a MAX 360 flex to the RIA5280 Denver users group.. I've updated the deck some with additional information that I've learned over the last couple of months.

So here is the most recent slide deck.

and the same blog references to the source code.

Memopal automation

So I use Memopal as my cloud based backup service. I like them because multiple computers can back up to a single account automatically. That's really its best feature. It lacks a public api and the web interface is a little clunky (like once you start running out of space and trying to figure out what to delete).

So I found that I had ~400 Itunes backup files being stored at 30MB each. And the 3-click per file + several seconds to delete  wasn't going to work for me. And there was no public API that I could code against, especially with session based authentication.

I couple of firefox plugins and a little hand editing in a text editor and 400 files, worth 12G gone in a few minutes.

Here are the details.

• Install IMacro for firefox for the automation
• Install Link Gopher for firefox
• Navigate to the folder with the files that you want to delete
• Use link gopher to get a list of all of the links on the page. 
• Copy the resultant html page and paste into a text editor
• Remove any files that you want to keep
• find "https" -> replace "URL GOTO=https"
• find "get?" -> replace "delete?"
• select all and copy
• create a dummy macro via record.
• edit the macro and paste
• play back the macro. 

It is the little things in life that are worth celebrating (and blogging).