The Priority Pyramid is a tool I use to stay on track with new consulting clients. It prioritizes how, who, and what I engage in at any given time. It can be overwhelming when thrust into a challenging situation, a code base in dire straits, and a frustrated team. You need a strong pillar of guidance.

This article goes over what parts make up the Priority Pyramid from a high level. I’ll talk about what milestones make up each section and how you navigate back and forward between the priorities.

When done, you should know how to engage your client’s team and tackle working on a large code base at a frustrated client site with 99 problems.

Why?

Over the years, I’ve prioritized what I need to be doing when working my consulting clients. There are countless things I need beyond “coding”, and all have to do with “people”. Code in its own right is challenging enough. Add people to the mix and it gets more complicated than it already is.

Every engagement is different, even with repeat clients. This is why I like consulting. Meet new people, travel new places, learn new things.

While I enjoy and thrive on improv, what I didn’t like was not having a set of guidelines to deal with each new client. The business blogs & books I’ve read are pretty dry, and don’t really focus on the people issues coders encounter and have to deal with. Most also assume YOU are the one creating & maintaing the app, not fixing/modifying a large one extremely behind schedule. It’s either sales, management, or product management. This includes the consulting books. Some approach it from a larger consulting perspective, where you come in, listen to the client’s problems, write up a plan, and pass it off to India. If you are involved, it’s just to either head off major disaster and/or provide face time for the client.

This is NOT what I, and my colleagues I’ve worked with over the years do. We’re in the trenches, working alongside our clients, playing the politics games whilst coding.

So, I made my own rules for engagement, prioritized based on importance, with verification points to ensure I’m on the right track. If I cannot work towards getting through all tiers of the pyramid, I will not be working for the client long, whether by my choice or theirs. It’s important I flush out these red flags early and tackle them full bore.

That… and it has D&D connotations.

Quantitative vs. Qualitative Foundations

I’ve used both quantitative and qualitative results from case studies, white papers, and my own experience to base this set of priorities on.

Mythical Man Month/Brooks’ Law: “Adding manpower to a late software project makes it later”. Some of the bad projects I’ve been on had too many people on them. Your goal at that point is to delegate refactoring to the team to compensate, lead with good architecture, and leverage your trust currency to guide the various teams into a direction you need them to go. Also known as software chaos management. This requires you be at a high enough level to be in charge of various teams. If you’re not, God help you.

Code Review: One person, reading code for up to but not exceeding 1 hour finds more code defects than unit testing. This is not peer review, but that is also effective. Citations: Code Review at Cisco Systems, Klocwork/Forrester “The Value and Importance of Code Reviews”, and some other stats from Code Complete. Keep in mind while most of the studies mention that defects do not significantly decrease after 1 person, the ability to learn from your peers and getting architecture suggestions are very well documented in the blogosphere.

Cheaper to Find Defects Early: Whether you are ruthless about upfront requirements gathering and/or initial architecture, or are adamant about short development iterations that includes scope reduction, both allow the ability to find more defects early. It’s easier to both find, and fix problems earlier than later for a variety of reasons (code size, feature acceptance, contractual obligations, etc). Beyond the IBM studies back in the 70′s here’s an excerpt from High Quality Low Cost Software Inspections. Also, crazy charts from Capers Jones (they have some other good studies). This is why I’m so adamant about getting the visual design (wireframes/design comps/ux/information architecture, etc.) right from the get go, even if 6 months into the project. Lowest hanging fruit and saves tons of time/money.

Distributed Development (PDF): The result that physical distance between developers doesn’t matter. Different room/building/country… not a big deal at all. What matters is how far the software developer(s) are from the stakeholder(s) in the organization management hierarchy. This is extremely important. I am firm believer in both telecommuting as well as on-site visits with clients for communication & leadership reasons. This is central to identifying the power structure of the organization in Tier #2 and garnering trust with those who can help you talk to who you need to talk to in Tier #3. I’ve been ineffective at more than one consulting engagement because I wasn’t  high enough to affect the required positive change.

Toyota Production System: Their continuous improvement philosophy and respect for people are what really ring true to me. While It Takes a Village to build great software, sometimes you have a crowded, drama filled city that you have to work within. Doing your best to get the team motivated to constantly improve, and SEE the improvement occur over time for motivation reinforcement, is just a small way to continually improve. You can only do this if you do in fact respect the people you work with. Empowering leaders amongst those who actually do the work can lead to effective production. You can use these Toyota Process strategies in your own team delegation.

The Priority Pyramid

The 8 steps are in order of importance:

1. Report
2. Understanding
3. Trust
4. Lead
5. Build
6. Explosions
7. Diagnostics
8. Architecture

While it implies 4 are about coding, make no mistake: The Priority Pyramid is all about people. It’s built on your relationships with them and those relationships ensure you can do your job.

Lets break down the tiers the following way: What milestones do you need to complete, how to do you move on to the next tier, and when should you move back? I make the assumption if you’re on a team, you’ll divide tasks appropriately.

A Note on Tier Foundations

Each tier works on top of the foundation of the former. If the foundation is weak, it won’t strongly support the one on top. If you don’t have the trust of management and your co-workers, it’s difficult to lead them. If you don’t have a good understanding of the company and people who work within it, it becomes very difficult to affect positive visual design changes to make architecture easier. It’s ok to be in Tier #8 and realize you need more understanding of how the application will be deployed from Tier #2; just like refactoring code over time, you can continue to strengthen the foundation tiers over time as well.

Tier #1: Report

Milestones Before Arriving

1. You’ve talked to stakeholder(s) on the project to have an idea of what you’re getting into.
2. Verify you actually want to get into it. Some consulting gigs are hard to get out of. Some can reflect poorly on your firm/you even if you do a good job. Make sure you’re willing to make the plunge. We’re looking for red flags here to save you tons of money and stress. I’m not saying be choosy, I’m saying be careful.
3. Where you’re going, who you’re supposed to see, and when.

Milestones

You/your firm has scored a client, you’ve booked your airfare + hotel, and you’re 1st day on-site has arrived. You look sharp, are excited, and looking forward to making a good first impression.

1. First question out of your mouth after small talk should be “Who’s do I report to?”. Yes, it’s ok to follow up this question once you’ve scored more rapport with “Great, so… who’s my boss?”. This ensures you don’t do good things that get you in bad trouble.
2. Second question: “What will make you happy when I leave?”. This helps verify why you’re really here, and what they’re really paying you for. Sometimes this takes alcohol to get the true answer. Sometimes just a neutral setting outside of the office/building.

Successful Exit

Know who you work for and your true goal in life for the next 8 months.

Tier #2: Understanding

The best communicators are good listeners. Your task now is to look people in the eye, lean forward, and listen well.

Milestones

1. Listen: Get people talking, asking questions, and listen to what they say. This is the most important step in the entire pyramid.
2. Goals: You need to understand what the goals are for the project, both stated and real. What are you and the client really trying to accomplish? Answering & documenting this will guide your actions for the rest of the project, overridden only by “Who do you report to?”.
3. Problems: What are the problems and challenges the company has run into? Do any relate to why you’re here? Do they have a thorough list or are there more? Solving problems earns trust, and helps in the next tier. It also validates your paycheck. Why does the client have those problems? Where do you fit in? Who’s accountable for identifying solution(s) for and solving those problem(s)? These are your first challenges in the game.
4. Dissect People: This is also an opportunity for you to start learning who the players are in the game. You need to understand what makes someone tick to best interact with them. Do they like business first, small later or the opposite? Do they have ulterior motives? Can they be trusted? Can they give you valuable intel on the project others won’t? What will it take to make them comfortable enough to tell you more? How can you possibly help them? You’re going to be spending the next 3 to 18 months with these people. Get to know them, make a good first impression, and understand them. These are the people you want on your team, who you want to do certain things for you, who you want to trust you. Once you understand them, you can effectively engage them. Sometimes this is done simply by watching how they interact with others. Ask questions to get them talking; their personality whilst reveal itself. Finally, figure out who reports to whom for real? What is the power structure? You’ll need to play within this framework; best to know how it works for real vs. what the label says on their door.
5. Explore: Finally, code stuff. Time for initial reconnaissance. Taken what you’ve learned, it’s time to verify what you heard is recent, relevant, and can be corroborated with the code. This should still be framed from a “learning the company” perspective. You need to:
1. Learn the Data Model: The VO’s, the Services it calls, and what those business objects actually mean to the organization.
2. Learn The Framework: How is the code architected; what framework did they use?
3. Understand The Story: With another developer, preferably one who worked on the code base and/or your client, ask the developer questions to learn the story. Even the worst code base has a reason how it got there. Like an archeologist, you want to understand this history, the pivotal decisions, or lack thereof, that made it the way it is. You’ll learn the to respect, and pity, even the worst code base once you’re armed with this knowledge.
4. Look For Red Flags: Both the currently benign, and the “holy eff we’re eff’d”. Whether that’s everything being a hashmap in Java, Angular & Backbone both being used in the same code base, or ActionScript 2. You don’t want surprises, you want to frame your perspective of the code base with your client’s. This is a VERY important step. Don’t say it, but talk about it internally in my mind. Find out why there is a disparity in perception.
5. Look For Mines: Like red flags, these are things that down the line of a project, based on what you learned above could go boom. They aren’t a priority but need to be documented.
6. Look For Validation: Did everything you learned in Steps 1 – 4 get validated or where you completely off? If so, continue to dig, and redo steps 1 – 4 to re-verify.

Successful Exit

When you firmly understand the client’s reality, the reality the code reflects, and the real reality once you’ve resolved the two, you’re ready to move on. If they still don’t mesh, keep asking questions & researching.

Tier #3: Trust

Assuming you’ve made good first impressions with those you’ve met, it’s now time to validate those initial impressions in those you’ve met. It’s time to start building trust.

Milestones

1. Provide Immediate Value: Check in code into the company’s source control your 1st week there. Preferably the code fixes a bug. Do NOT try to save the world in the code base. Pick some litter instead. If you clean the entire thing in a day, great, but get your feet wet and see what happens. A lot of drama and things you couldn’t predict happen AFTER you’ve checked in code and it goes into production. Start small and work your way up. Just ensure it’s immediate.
2. Make Professional Friends: Respect those you work with and get to know them. Whether this is small talk that’s sincere or genuine interest, whatever works to build a positive relationship. People trust those they like. Trust is a currency you’ll sometimes have to spend in buckets to make positive headway so start investing in earning some now.
3. Visible Logger: Invest in a visible logger. Even if the code doesn’t currently have problems, when it does, you want it to talk to you. Not only you, but the company. You want to corroborate this communication with your boss. When production explodes, and you know within seconds because your little secret keyboard shortcut debug window shows the error, that inspires confidence. It also provides a kind of transparency to your client when others start using it proactively to find problems. You just empowered a company to work together; well done, that’ll earn some trust. Make the code talk to you so you can trust what it’s saying, then expose this communication channel to your client.
4. Provide Transparency: As you start getting your feet wet, whether this is struggling to get your environment setup so you can compile, or are deep in the bowels of fixing your first bug, let your boss know. Keep them appraised of what you’re doing on regular intervals, even if she doesn’t ask. Come across with confidence; you KNOW what you need to be working on, and you’re informing your boss as such. Additionally, she has a chance to re-prioritize if you need to be working on something more pressing. No communication, and neither of these things happen. If they know and have confidence in you doing what you say you’re going to do, they can play defense and keep their boss off your, and your team’s back.

Successful Exit

Do you think people trust you? Have you checked in working code that fixes a problem and your boss has verified this? Can you even compile? Do you know the names of those you’re working with/near? If yes to all, you’re ready to move on.

NOTE: If you ever lose trust, fall back to continually adding immediate value. Trust isn’t given, it’s earned. If you lose it, the only way to get it back to is re-earn it from scratch.

Tier #4: Lead

At this point you know enough about the goals of the project to start formulating plans on moving forward, whether this is how to implement new features or how to fix/refactor existing ones. You’ve provided enough value to earn a modicum of trust. It’s time to lead people forward.

A manager puts people in a line, puts the guy with the machete at the front, and leads people through the jungle effectively. A leader climbs the tree, and tells everyone they need to go left instead.

Milestones

1. Short Term Goals: You’ve assessed the situation and identified priorities that need to be refactored (using my previous article). You need the team to agree on a common logging interface, both in code and visually. Finally, you need the team to agree on an architecture.
2. Long Term Goals: You’ve identified architecture holes that need to be plugged. Sometimes there are design problems that if changed could save months of work and hardship. You need to start work and documentation on it now. Solidify the long term goal into something defendable, and get the teams input. Be careful how you go about talking about it. While you need client feedback (remember transparency), it must be attainable to company-relevant, short term steps. You can spend trust currency for longer term refactoring/re-architecture endeavors, but I recommend against it.
3. Resources: Sometimes you need to hire additional people, whether from internal client teams, additional consultants/contractors from your firm, or hiring on behalf of your client. This could be staff augmentation or hiring a specific skill set you need/want. Identify these early and ask your boss.
4. Divide, Delegate, and Conquer: Whether the client’s employee’s or your firms, you need to divide up the massive amount of work amongst people. Offer up tasks first, and then assign to those you deem appropriate if no volunteers materialize. Building upon Tier 2 and 3, you should have a gut feeling for who’s best for what task. You cannot save the world by yourself. It may seem that you spend more time aiming people in the same direction then actually walking that direction yourself. Don’t fret; you’re on the right track.
5. Be Positive: While misery loves company, people like and follow positive people. In talking & delegating all of your goals, plans, do so positively. You’re not “fixing a pile of rubbish”, you’re “building an awesome application” or “improving an important machine” or whatever you can say and actually believe when you say it. Eat right, exercise, and/or surround yourself with positive influences. Make this the year you commit suicide, reorganize & clean your working environment/home office, or just accomplish a small goal that’s not work related that you use as positivity fuel. Mentor & encourage your team but don’t come off as a know-it-all/holier-than-thou. Play to win.

Successful Exit

If you know what you/your team needs to be working on today, next month, you’ve approved the hiring you need, and the team is all tasked up, then it’s time to move on.

Notes on Tier #5 – 8

The latter teirs are development specific, but rely on a strong firm foundation from the first 4. Remember, the human component is your weakest link, not your Factories. Strengthen them; do not enter these 4 latter tiers of first 4 are weak.

Tier #5: Build

You need to easily build the software. This is the most common, and frequent, option you’ll do many times a day, every day. The longer this takes, the longer it takes you to develop. This can also kill your team’s momentum. If something goes wrong, such as someone checking in a bug that breaks the build into source control, or a feature needing be implemented for a presentation by some date, a slow build exacerbates time to resolution.

Worse, some developers will start making their own build setup, leading to code that works on some developers machines and not on others. Validation of working code suddenly becomes meaningless which can adversely affect project schedule metrics. Even worse, you can think your code works, but it doesn’t for others. Who’s right?

Milestones

1. Quick: The build needs to run quickly. This obviously an arbitrary metric based on code size, libraries, continuous integration setup, etc. If developers say “the build is slow”, then it’s slow. Utilize libraries so the entire thing doesn’t have to compile, inject dependencies at runtime, utilize modules… whatever it takes.
2. Easy: If the build is complicated to do, you’ll get developers making a lot of mistakes during code validation time before they check in. They’ll either check in bad code, or make their own setup that allows the code to work on only their machine. They should be able to just click 1 button, run an Ant/Maven script, or do a 1 line command line execution.
3. Duplicated: The build should be able to be duplicated on a new developers machine. It’s completely fine to have company standards, such as only Windows 7 PC w/admin rights, Flex SDK 4.6, running Rake 0.8.2. It’s also ok if that takes some time with another developer to setup. What’s not ok is once they do that, it doesn’t work. If there are 3rd party dependencies that cannot effectively be deployed x-machine, find a way to remove them. Solutions include, again, using libraries, modules, development servers vs. local server setup, etc.

Successful Exit

If you can run the build multiple times a day without pulling your hair out, it can be run multiple times on the same code base and not break, and anyone on the team can explain to a new developer 90% of the setup, you’re good to go. Another validation includes Developer A checking in code, then Developer B updating to latest and running the build and it works on their machine as well.

Tier #6: Explosions

When things go awry, you need to immediately know where and why. More than a euphemism for errors/exceptions, explosions also include errors in the application that constantly cause fire drills in the company.

Milestones

1. Exceptions Handled: Handle all errors save null pointers. If you have global exception handling capabilities, implement it/them. This doesn’t mean just wrapping something in a try/catch; it means not only logging the catch, but putting something meaningful in the catch so you’ll understand what it means when it happens.
2. Logging: You need to centralize all long into a single library. It’s ok if this library is your own that builds on top of the built-in provided one, such as Flex’ ILogger. As long as anyone, anywhere on the team wants to log something, they use that vs. print/trace.
3. Visual Log: Optional: A visual window, built into the application itself (SWF/JS, etc), that prints out the log levels. This is done to allow logs to be seen by developers, not users. It also allows non-developers, especially QA, to proactively find problems and talk directly with those responsible vs. the 1st developer they can find. The value this provides in empowerment and time saved should not be underestimated.
4. No More Fire Drills: Wrangling in challenging errors to help prevent fire drills can do 3 things. First, you score a lot of trust in “knowing” why something is wrong vs. 10 people running around aimlessly trying to figure out why. Second, you can clearly cite accountability; is it the server-side team, your team, or the database team? Instead of yelling “I think your stuff broke” you can confidently say it did with helpful data for them to test against. That kind of attitude is much easier to solve problems with. Third, fire drills no longer sabotage your productivity.

Successful Exit

If an error occurs and you know where it happened, a general reason of why, and who’s potentially accountable, you’re in insanely good shape. Users don’t see these errors, just null pointers, or those you’ve built a GUI for (ie Alert error dialogue). Bonus points if fire drills happen on other teams that aren’t related to yours… but you have a way of helping through logging to make testing easier.

Tier #7: Diagnostics

Diagnostics form a range of tools, not just code. They are anything that helps provide insight into code issues or runtime errors without costing more overhead in maintenance than the value they provide. The reason diagnostics is before architecture is that in larger applications, especially in a consulting context, adding simple diagnostics has a ton of value with little effort whereas architecture takes a ton of effort but tends to have low perceived value (yes, it’s valuable, just harder to sell).

Milestones

1. Unit Test Coverage: Even if you’re not doing TDD, unit tests along help find & prevent bugs as well as improve API’s. Unlike code reviews, they don’t get tired, benefit the entire team, and if written well only slightly add to code maintenance. Finally, they can be automated. These are also great things to work on in down times such as when JIRA is cleared, you’ve hit a brick wall with another bug, or are waiting on dependencies for a feature.
2. Integration Tests: These are my favorite on service layers, more so than unit tests. The reason being is most of the Flex projects that I’ve worked on in a consulting context had some form of service layer problem; ie how they talk to the back-end. Both refactoring the service code and writing unit tests that allowed me to automate the testing. It’s also nice to quickly know what part broke with confidence; client, server, or database. Automating these also makes you feel better when the server guys test new code, you can quickly help them test. There are more to integration tests, but these are the low-hanging fruit of ‘em.
3. Automated Builds: Expanding upon Tier #5, streamlining your build process to be more inline with continuous integration practices. This means designating a resource to setup, and maintain, a continuos build tool like CruiseControl/Hudson/TeamCity, etc. You should know who checked in bad code and when.
4. Custom Diagnostics: Some applications have challenging domains of complexity. For example, video; there are TON of things that can go wrong at runtime even if the code compiles just fine. There are also a sequence of events that can cause video to fail, and knowing this sequence is paramount in debugging it, or shrugging it off since there’s nothing you can do (i.e. CDN is down). More importantly, though, sometimes you need a way to glimpse this in a more visual way than a logging window can provide. Conversely, sometimes you need to see environment variables in real-time. This little window can verify your application is running in the mode you think it is for a developer in another country. Simply making a box with a text field in it that showed Flash Player’s sandbox security type saved me 3 days (I lost 3 figuring this out, heh). Additionally, they can help empower others to do testing & diagnostics on their own. Just be careful these are not a security risk for code and/or company information if deployed in production.

Successful Exit

If you have good unit test coverage, can automate their running, your build is automated in some fashion (even if just client side only), and you have gui or command lines way to gain insight to your running application to find out more about errors, you’re in awesome shape.

Tier #8: Architecture

While good architecture requires a book full of information + years of experimentation to get right, what we’re concerned with here is IMPROVING existing architecture. If you are starting a project from scratch and own the architecture, great, use this phase for maintenance. Otherwise, we’re looking for that sweet spot of a 1 day change for a more decoupled, easier to use & test in code system. If something takes longer than 3 days, you’ll be hard pressed to merge it back in and not inconvenience other developers… unless it’s very little code.

Milestones

1. Tight Factories: Any part of your application which takes outside data into it’s system, such as external JSON/XML as well as user input, needs to be further hardened. DRY the code, layer with #moarUnitTests. Form a convention on what happens when parsing/decoding fails; do you throw errors or return null and log them, thus passing the burden of handling null to your system? Decide as a team.
2. Fault Tolerant Services: Whether to a back-end, an external call to JavaScript in a host page, or an ad library… if it’s not your code, it’s a service. Make sure you wrap that with a Proxy that can NOT explode, and logs everything that went wrong. That extra 20 minutes pays off mad dividends.
3. MVC/MVP/MVVM/YourMom/SC/PV/PM: As a team, pick one an over arching architecture pattern and stick with it for new code. I like Supervising Controller, while others of my front-end  ilk like Presentation Model. A lot of JavaScript web frameworks follow more of a Passive View. The only right choice is team consensus & comfortability. Then endeavor as a team to get certain parts moving in that direction. If there is old code, and you’re currently working on it, see if I can convert in less than a day to make more congruent with the rest of the architecture.
4. DRY: If none of the above can be improved, simply making code more DRY is a good fall back task to more unit test coverage.
5. TODO/FIXME/KLUDGE/HACK: Do a find all in the code. If you see those, fix them. #fixBrokenWindows

Successful Exit

You never really exit Tier #8; in fact you tend to loop back to either 7 or 6 and 7 and then back to 8. However, if you find yourself working on new features, or fixing bugs with no other drama and the rest of your team is doing the same… then you’re in epic shape.

Conclusions

As you can hopefully see, my priority list helps keep you focused on delivering value to those that matter quickly. Good software development is iterative. Earning trust is also iterative; you don’t take people’s money and disappear for 6 months (that’s called good Capitalism via Waterfall). This whole list, while referring to software development, is all about relationships with people. Excluding code review, your challenge as a leader is delegating the tasks in each tier to divide & conquer, mitigating conflicts, and solving hard software problems in addition the rest of your responsibilities.

Each tier builds upon the former all the way down the line. While deep in the bowels of fixing explosions in Tier #6, I’m still continuing to build meaningful relationships in Tier #3.

Remember:

1. Report: Know your true boss and what will make her happy.
2. Understanding: Listen, learn about the company, the people, and dive into reading the code.
3. Trust: Earn trust by providing immediate value.
4. Lead: Take the initiative and move the team forward. Delegate, divide, conquer.
5. Build: Make the build fast, easy, and capable of being duplicated if need be.
6. Explosions: When things go awry, you need to immediately know where and why. Prevent fire drills.
7. Diagnostics: Get good unit test coverage, integration tests, automate your builds, and build any custom diagnostic tools needed.
8. Architecture: Decide on a direction/framework, and continue to nurture the code, and developers, in that direction. Loop back to 6 & 7 if need be.

Title photo by Ewan Monro is under a Creative Commons – ShareAlike Attribution license.

Refactoring is the discipline of applying a multitude of small, low-risk techniques to a code base in order fix and improve it. While corroborated by the software community, employing such techniques in a consulting context can be challenging because people are involved, often in a negative situation.

You need 2 weapons to win the refactoring battle. First, you need to understand what refactoring techniques are at your disposal and how to implement them. Below, I’ve listed the core ones I see needed time and time again. Second, you need to have a plan on how you engage the client company and their employees to allow you to do the first. That’s covered in the next article.

I’ve talked about how you do various parts of these initiatives in previous articles. What I want to talk about today is 1 of the 2 things: The core things you need to be concerned about in refactoring. In the next article we’ll talk about a prioritized plan you should follow when engaging a client where refactoring is needed. These are aimed at being used in the worst situations, but can provide positive benefits in benign or benevolent situations as well.

You should be able to take this blog post and the next, and from them both progressively improve a poor quality code base as well as engage a challenging client amongst challenging circumstances.

Note On Languages

I’ve intermingled JavaScript, ActionScript, and Lua to help provide a variety of examples, show this list is technology agnostic, and provide corroboration of techniques across technologies. That and I miss coding Lua since I’ve been so busy and needed an excuse. This does have a strong focus with front-end languages, namely those which run in a browser.

Nomenclature

Factory/Decoder/Parsing: Taking any kind of data, such as JSON or XML, and converting  into something you need it for. This could be as simple as accessing properties on it to converting it to a completely different type of object, or even creating new objects from it.

Coding Conventions

• Factory Errors vs. Null: Below, I’m using both error and null. Error means if a Factory/function/decoder fails in anyway to understand its data, you throw an error. This helps in unit testing, and expose errors early in the weakest part of a front end application; those that utilize non-strongly typed data. Optionally, when you find a parsing error, you return null instead. Consumers of the Factory must test for null, but you mitigate runtime exceptions and expose faulty consumers. I like using both, but it’s a lot of work to be sure.
• Don’t Create Grenades: Regardless of language, you shouldn’t create grenades. This means don’t use throw/error. Instead, dispatch a custom error event that is opt-in. Consumers shouldn’t have to worry about the code they’re using bubbling up problems to their area of worry unless they’ve opted into those concerns. ActionScript, JavaScript, and Lua also don’t have a strongly typed ways to verify with the compiler that these contracts have been met, unlike Java’s throwable. Thus, don’t throw, inform to those who wish to know. Log regardless.
• Factory vs. VO Self Parsing: Some like Factory’s to parse external data (JSON/XML, etc.) into ValueObjects for an increased likehood of DRY code (shared parsing code that’s easier to unit test). Others like ValueObjects to serialize/deserialize themselves to reduce coding overhead as well as make the API easier to use. I’ve used both below, but I’ve found this is usually a team decision and also depends on how complex your VO’s are.
• Model vs. Command vs. Remote Proxy: From architecture perspective, some people prefer to have a Model handle Application Data, and a Command/Controller/Presenter handle remote Service calls to update that data. Some prefer wrapping both inside of a Remote Proxy (basically a Model that has serivce(s) inside it), and allowing Controllers/Mediators/Presenters/ViewControllers to make calls on those Remote Proxies. I use both Model & Commands below, but no Remote Proxies. It’s up to you and your team which you think is best. If you’ve gotten this far in the discussion, you’re clearly better off than most. The point here is solve for Model and/or Application logic encapsulation.
• try/catch: I use try/catch liberally. Developers concerned about performance, such as game developers or those using complicated parsing algorithms should take note the significant performance cost of try/catch as well as liberal use of ExtractMethod. This article assumes the code is in bad shape and you/your team needs to refactor it over many months to ensure your team can prevent fire drills, meet milestones, and start to build a firm foundation. If the code base has the following problems outlined in this article, your first order of business should be fixing them first before you start optimizing. If you really need performance, just use unit tests instead and pray.
• Singletons: While not a replacement for global variables, and generally frowned upon, well written ones are a good first step if they have access control and utilize strong-typing. (ex Model).

Refactoring Basics

Improving existing code can be done in 3 ways: handling exceptions, using a good architecture, using strong-typing if available, and following refactoring paths. The reason you use refactoring, especially in a consulting/contracting context with existing code bases is that you’re not allowed to rewrite them from scratch. Thus an unwritten bequeathment of responsibility occurs between the code base and you: it now becomes your problem. Its failings become your failings. The insecurity it gives your client now has them project that insecurity, and responsibility to remedy it, onto you.

I’m assuming you’ve already done a code review by this point to ensure you, or your firm, want to even get involved. If you don’t but are still here, it’s probably because they’re paying you a lot of money to wallow in their mess. In that case, welcome to the suck.

The original definition of refactoring, referring to Martin Fowlers here, is making a small, positive change that has low inherent risk. This is done to ensure you don’t break anything. The theory is, over time if you make enough positive changes, you’ll make the whole code base positive.

Life is more complex than that, but the point here is that you use refactoring to affect positive change without breaking the code and looking like an idiot in front of your client and ticking off their customers. You do not make large, sweeping changes to the code base, even if they are needed. Take it slow and steady, 1 little change at a time. Some of the examples below are small (such as using strong-typing in place of Object and *), and some are larger (such as modifying your Model layer) are larger. Sometimes such changes you need help in tackling because it’s sphaghetti code; team refactoring can be invigorating and you get a lot more done, so don’t think you have to do this on your own.

When in doubt, make a small, positive change. If you take more than 3 days to make a change, abort.

Exceptions

Your first priority in refactoring should be handling exceptions or errors. It’s ok if you see how sausage is made in the meat factory, but it’s not ok if your client does. You can turn explosive bedlam into a controlled spectacle. That’s right, things breaking can be made into looking like your in total control. Magic isn’t magic; it’s sleight of hand through distraction.

“Look at this pretty logging window created by our company to handle such situations. All errors are now known to us, when and where they happen. This awesome ability to report said errors amongst your staff, not just QA, but you, your customers… everyone, even while in production! No surprises or fire drills here… ALL at no extra charge.”

But how do we get there? Let’s start at bottom.

A lot of programming languages execute functions or methods in 2 modes: protected or omg-it-might-blow-up-we’re-hardcore mode. JavaScript/CoffeeScript, ActionScript, and Java for example use try/catch. Ruby uses begin & rescue. Python uses try/except. Lua uses pcall. Most languages have various ways to ensure that if code explodes, it’s done so in a controlled fashion. Additionally, some have global exception handling as well.

Exceptions are the first area of uncontrolled chaos that must be contained. No controlled refactoring can take place without tackling these areas first.

Architecture

Architecture comes into play for large code bases, although, using it for small code bases can help you learn (albeit hard to appreciate as it’ll often get in your way of getting r done).

Architecture refers to how an application is built. It’s usually an amalgamation of design patterns used in a common way. For the sake of this article, we’re using architecture in a small sense of the word in helping move parts of the code to be more encapsulated, make things that break easier to identify, test in isolation, that sort of thing. While references to MVC/MVP/MVVM can get really esoteric and subjective, we’re not concerned with that.

What you need to verify with defining “good architecture” for you and your team is how it works, agree on approach, and ensure it helps you test things in isolation. If y’all agree, can be independently productive, and if something breaks you know where… that’s good architecture. Don’t get hung up on the definitions, get hung up on the contract on how things talk to each other, and that your team all agrees on that contract. This’ll come into play later in the next article regarding team synergy.

Strong Typing

Not much to say here. Don’t use Object/*/Dictionary. If you do, wrap it with a strongly typed API or unit tests. Putting the burden on the consumer of those objects leads to lots of code. Lots of code == bad.

Don’t do this:

var person:Object = {};
person.firstName = "Jesse";
person.lastName = "Warden";

Do this:

class PersonVO
{
   public var firstName:String;
   public var lastName:String;
}
 
var person:PersonVO = new PersonVO();
person.firstName = "Jesse";
person.lastName = "Warden";

When you don’t have strong-typing (JavaScript/CoffeeScript/Lua), #moarUnitTests. For JavaScript use jshint, jslint, and annotations that various frameworks use to infer type like Google’s Closure compiler for great justice.

Refactoring Paths

Beyond the suggestions below + mentioned resources, you have to use your own intuition. Refactorings on their own are good but when done as a team effort in strategic areas, you can make greater headway, earn more trust from your client, and do more “relevant” refactoring.

There are some things you’ll know are right such as investing in a good GUI logger, making friends with IT, etc. Others, on what to fix first, how to support dual architectures in some areas, and how to portray transparency to your client… some of those are just experience. When in doubt, go with your gut. The less code of the choices, the better.

A good refactoring path allows you the ability to code right now, satisfy non-programmers for trust earning, with assurance you haven’t coded yourself into a corner. It’s like a good marriage: compromise.

You’ll lose some battles. The goal is to win the war.

You’ll have detractors such as who don’t have their Code License; knowing the rules before breaking them… or some who are just afraid. Some are ivory tower zealots who aren’t punished for getting nothing done (some are rewarded). Some have emotional scars from attempting to fix things, and are hesitant to do what’s right. This is usually when they know the value but cannot effectively articulate it to stakeholders (this is called a “software developer”). Some are just insecure and don’t believe in their own refactoring ability and thus hold you back as well (low D on DISC). Some think you’re full of it.

Refactoring is temporal. You are creating a positive change to last for awhile… but not forever. It’s ok to refactor something, then refactor it again later as long as you’re actually making an improvement upon a problem. If a ship is taking on water, the first thing you do is plug the holes with wooden spikes. Later, when the French stop firing at you and your hangover is gone from drinking all the wine you found on their now apprehended ship, you can plug the holes proper with a leather & tar mixture. Then once in dry dock, replace the planks.

Architecture is not temporal… but can be as well. You’re supposed to establish rules and guidelines on how you approach a code base. Sometimes, however, you can jury-rig a solution to hit some deadline, or get a build out the door for some managerial milestone. Later, you can re-assess. Sometimes, you’re initial hack is controlled; meaning you are writing throwaway code on purpose. In doing so, you can make it easier to fix later.

Architecture is generally decided upon by the team, and you move forward for the length of the project on it.

Refactoring is a strategy that can change daily.

Step #1: Exceptions

Case: Service layer has 3 failure points: entry, error, and exit parsing.
Solution: Validate post data, log error, wrap parsing/factory/decoding.
Language: JavaScript using AmplifyJS

Bad Code:

amplify.request.decoders.appEnvelope =
    function ( data, status, xhr, success, error )
    {
        if ( data.status === "success" )
        {
            success( data.data );
        } else if ( data.status === "fail" || data.status === "error" )
        {
            error( data.message, data.status );
        } else {
            error( data.message , "fatal" );
        }
    };
 
amplify.request.define( "decoderExample", "ajax", {
    url: "http://server.com/service/doSomething/",
    type: "POST",
    decoder: "appEnvelope"
});
 
amplify.request({
    resourceId: "decoderExample",
    success: function( data )
    {
        data.foo; // bar
    },
    error: function( message, level )
    {
        alert( "always handle errors with alerts." );
    }
});

Refactored Code:

/*
Our decoder function is now:
1. shielded from bad data
2. assumes the response not well formed from the get go
3. logs each parsing error separately for easier diagnosis
*/
 
// modified appEnvelope decoder function
function ( data, status, xhr, success, error )
{
    try
    {
        if(data == null || data == "")
        {
            error("Decoding error in parsing data.");
        }
        else if(data.status == null || data.status != "")
        {
            error("Unknown status.");
        }
        else if(data.message == null || data.message != "")
        {
            error("Uknown message.");
        }
        else if ( data.status === "success" )
        {
            success( data.data );
        }
        else if ( data.status === "fail" || data.status === "error" )
        {
            error( data.message, data.status );
        }
        else
        {
            error( data.message , "fatal" );
        }
    }
    catch(e)
    {
       error("Decoding error.");
    }
};
 
/*
Notice we:
1. Validate our requestData (you could do more than a null check) before making an actual service call.
2. Additionally, we log the failed request with the Service name and reason for easier diagnosis in a larger application.
*/
 
if(requestData != null)
{
    amplify.request({
        resourceId: "decoderExample",,
        data: requestData,
        success: function( data )
        {
            data.foo; // bar
        },
        /*
        Our request error handling now has:
        1. a log, vs. an alert, for logging our error
        2. a common logging signature for easier diagnosis in a larger application
        */
        error: function( message, level )
        {
            console.error("MyService::error, message: " + message + ", level: " + level);
        }
    });
}
else
{
    console.error("MyService::error, requestData is null.");
}

Case: Null values in GUI. View/GUI must assume data is not always good; must handle null without exploding.
Solution: Check for null using if/then.
Language: ActionScript 3

Bad Code:

myTextField.text = person.name;

Refactored Code:

/*
We now:
1. check for a null VO first
2. if it is in fact null, we have a visual, conventional way of displaying null values w/o exploding.
3. if a property of the VO is null, that'll display as normal (in this case as an empty String)
*/
 
if(person)
{
   myTextField.text = person.name;
}
else
{
   myTextField.text = "???";
}

Case: Global Exception Handling
Solution: Add global handler that logs errors away from users to see.
Language: ActionScript and JavaScript

Refactored ActionScript Code:

package
{
   import flash.display.Sprite;
   import flash.events.Event;
   import flash.events.UncaughtErrorEvent;
 
   public class ErrorHandling extends Sprite
   {
      public function ErrorHandling()
      {
         super();
         addEventListener(Event.ADDED_TO_STAGE, onAdded);
      }
 
      private function onAdded(event:Event):void
      {
         loaderInfo.uncaughtErrorEvents.addEventListener(UncaughtErrorEvent.UNCAUGHT_ERROR, onUncaughtError);
      }
 
      private function onUncaughtError(event:UncaughtErrorEvent):void
      {
         trace("Uncaught Error: " + event);
         try
         {
            // note, fails in Asyncronous errors
            throw new Error("stack trace creator");
         }
         catch(error:Error)
         {
            trace(error.getStackTrace());
         }
      }
   }
}

Refactored JavaScript Code:

// via http://stackoverflow.com/questions/951791/javascript-global-error-handling
//
// more techniques here for Opera/Safari older versions
// http://stackoverflow.com/questions/645840/mimic-window-onerror-in-opera-using-javascript
//
// also note various browsers pass different arguments, and some suggest
// handling existing handlers if they exist
// https://developer.mozilla.org/en/DOM/window.onerror
//
// also note that the error in some browsers will still occur unless you handle it
// a certain way; here we're returning true from the error handler to do so.
 
window.onerror = function()
{
    if(arguments && arguments.length && arguments.length > 0)
    {
        var logStr = "";
        var len = arguments.length;
        for(var index = 0; index < len; index++)
        {
            logStr += "\t" + arguments[index] + "\n";
        }
        console.error("Global Error:\n" + logStr);
    }
    else
    {
        console.log("Global Error");
    }
    return true;
};

Step #2: Architecture

Case: Encapsulation of statefull, Model data.
Solution: Encapsulate Setting of Model Data to single place (DRY)
Language: Lua in Corona SDK

Bad Code:

_G.score = 0
 
local scoreText = display.newText()
function updateScoreText()
   scoreText.text = _G.score
end
updateScoreText()
 
local powerUp = display.newImage("powerup.png")
powerUp.name = "powerUp"
 
local enemy = display.newImage("enemy.png")
enemy.name = "enemy"
function enemy:collision(event)
   if event.phase == "began" then
      if event.target.name == "bullet" then
         _G.score = _G.score + 1
      end
   end
end
enemy:addEventListener("collision", enemy)
 
local ship = display.newImage("ship.png")
function ship:collision(event)
   if event.phase == "began" then
      if event.target.name == "powerUp" then
         _G.score = _G.score + 1
         updateScoreText()
         return true
      end
   end
end
ship:addEventListener("collision", ship)
 
function onTouch(event)
   if event.phase == "began" then
      local bullet = display.newImage("bullet.png")
      bullet.name = "bullet"
      return true
   end
end
 
Runtime:addEventListener("touch", onTouch)

Refactored Code Round 1:

--[[
Notice we've added an addScore method to:
1. have a central place everyone can update the model data
2. make it easier to identify WHO is calling this add function
3. ensure we never forget to update our Text Field with the latest value like in the original code
]]--
 
function addScore(amount)
   _G.score = _G.score + amount
   updateScoreText()
end
 
-- Fixing our enemy collision handler to now call our encapsulated method
function enemy:collision(event)
   if event.phase == "began" then
      if event.target.name == "bullet" then
         addScore(1)
      end
   end
end

Refactored Code Round 2:

--[[
Now we use a more generalized Observer pattern, and dispatch an event
when the value changes. The system is free to listen to this event
and react however it needs to. This allows the GUI to change w/o worrying
updating the model changing behavior to compensate for a changing GUI API.
]]--
 
function addScore(amount)
   _G.score = _G.score + amount
   Runtime:dispatchEvent({name="onScoreChanged", newScore=_G.score})
end
 
-- we now can update more GUI parts as they become needed
function onScoreUpdated(event)
   updateScoreText(event.newScore)
end
Runtime:addEventListener("onScoreChanged", onScoreUpdated)
 
-- notice this includes encapsulated GUI controls as well;
-- they can just listen in on the Event Bus.
-- Here, we have a Level Progress bar that listens to the score change
-- to visually indicate how far along the user is until they level up.
require "com.company.project.controls.ProgressBar"
 
LevelUpProgressBar = {}
 
function LevelUpProgressBar:new()
 
   local bar = ProgressBar:new({width = 100, height = 60})
   bar.levelMax = 1
 
   function bar:onScoreChanged(event)
      self:setProgress(event.newScore, self.levelMax)
   end
 
   function bar:onLevelMaxChanged(event)
      self.levelMax = event.newLevelMax
   end
 
   Runtime:addEventListener("onLevelMaxChanged", bar)
   Runtime:addEventListener("onScoreChanged", bar)
 
end
 
return LevelUpProgressBar

Case: Access Control for Statefull Model Data Using Application Logic (English: you need to update some model data, and multiple parts in your application need to do this). aka, removing global variables.
Solution: Utilize Proxy Pattern or Command Pattern for single access (DRY), this ensures there is only 1 way to update your model data, inputs are validated. This makes it easier to debug who is calling/invoking it, and what data they are passing, as well as ensuring those who need to know about the change are informed.
Language: ActionScript

Bad Code:

var firstName:String             = firstNameTextInput.text;
var lastName:String              = lastNameTextInput.text;
var birthdate:Date               = birthdateControl.value;
var myPersonVO:PersonVO          = new PersonVO(firstName, lastName, birthdate);
MyStaticModel.person             = myPersonVO;
MyStaticModel.person.lastName    = "McTaggart"

Refactored Code:

// First we create a factory class to test our creation & validation in isolation.
// This is also easier to write unit tests for. It's also DRY in that all classes
// who need to create PersonVO's and validate them are using the same code to do so.
 
class PersonFactory
{
   public static function getPerson(firstName:String, lastName:String, birthdate:Date):PersonVO
   {
      if(firstName == null || firstName == "")
      {
         throw new Error("firstName cannot be null nor an empty String.");
         return;
      }
 
      if(lastName == null || lastName == "")
      {
         throw new Error("lastName cannot be null nor an empty String.");
         return;
      }
 
      if(birthdate == null)
      {
         throw new Date("birthdate cannot be null.");
      }
 
      return new PersonVO(firstName, lastName, birthdate);
   }
 
   public static const validateLastName(lastName:String):Boolean
   {
      if(lastName != null && lastName != "")
      {
         return true;
      }
      else
      {
         return false;
      }
   }
}
 
// Second step, create a change event that those who need to know about a changing
// personVO in the model can be made aware of.
 
class PersonModelEvent extends Event
{
 
   public static const PERSON_CHANGED:String = "personChanged";
 
   public function PersonModelEvent(type:String)
   {
      super(type, false, true);
   }
 
}
 
/*
Third, create a Model class Singleton that:
- dispatches change events when it's internal person variable is changed, or modified
through accessor controls
- validates creation & changes
NOTE: If classes need to operate on PersonVO itself, create additional methods to
operate on the internal PersonVO to ensure proper change events are dispatched.
NOTE: For those who wish to remove Singletons, create as an instance, and inject the dependencies,
whether via a DI framework such as SwiftSuspenders/Guice/Spring, or manually via
getter/setters for those classes who need instance access.
*/
 
class PersonModel extends EventDispatcher
{
 
   private var _person:PersonVO;
 
   public function get person():PersonVO { return _person; }
   public function set person(value:PersonVO):void
   {
      _person = value;
      dispatchEvent(new PersonModelEvent(PersonModelEvent.PERSON_CHANGED));
   }
 
   public function PersonModel()
   {
   }
 
   public function setNewPerson(firstName:String, lastName:String, birthdate:Date):void
   {
      // first, validate data is good, don't want to pollute our model
      var personVO:PersonVO;
      try
      {
         personVO = PersonFactory.getPerson(firstName, lastName, birthdate);
         person = personVO;
      }
      catch(error:Error)
      {
         trace("PersonModel::setNewPerson error: " + error);
      }
   }
 
   public function updateLastName(lastName:String):void
   {
      if(person)
      {
         if(PersonFactory.validateLastName(lastName) == true)
         {
            person.lastName = lastName;
            dispatchEvent(new PersonModelEvent(PersonModelEvent.PERSON_CHANGED));
         }
         else
         {
            trace("PersonModel::updateLastName, failed because the lastName '" + lastName + "' is invalid.");
         }
      }
      else
      {
         trace("PersonModel::updateLastName, failed because the current person is null.");
      }
   }
 
   private static var _inst:PersonModel;
 
   public static function get instance():PersonModel
   {
      if(_inst == null)
         _inst = new PersonModel();
 
      return _inst;
   }
}

Refactored Code 2:

/*
In the case of need of many needing to affect the Model, and there is no
desire to all Models/Proxies to have public methods accessible by others,
you can use the Command pattern. Additionally, this solves the use case
where multiple Models are needed to be accessed and/or modified. Finally,
we also handle asynchronous use cases where you need to update a Model(s)
based on a server response. Notice how each step is validated, and a log is
produced if any step fails. You need to know WHERE it failed and WHY.
Also, no rollback support in the following.
*/
 
class CreatePersonEvent extends Event
{
   public static const CREATE_PERSON:String = "createPerson";
 
   public var firstName:String;
   public var lastName:String;
   public var birthdate:Date;
   public var personModel:PersonModel;
   public var organizationModel:OrganizationModel;
 
   public function CreatePersonEvent()
   {
      super(CREATE_PERSON);
   }
}
 
class CreatePersonCommand extends AsynCommand
{
 
   // injected dependencies; you could use a DI framework,
   // wrap Command class creation with these, or simply pass
   // in through the Event payload like the below shows.
   private var personModel:PersonModel;
   private var organizationModel:PersonModel;
   private var createPersonService:RESTFullCreatePersonService;
   private var personVOToCreate:PersonVO;
 
   // Create a PersonVO, set on the PersonModel,
   // and ensure the OrganizationModel is updated with the
   // new person once the server has verified it's creation.
   public function execute(event:CreatePersonEvent):void
   {
      try
      {
         personModel = event.personModel;
         organizationModel = event.organizationModel;
         personVOToCreate = PersonFactory.getPerson(firstName, lastName, birthdate);
         if(personVOToCreate != null)
         {
            createPerson()
         }
         else
         {
            throw new Error("ERROR: CreatePersonCommand::exeucte, PersonFactory returned null.");
         }
      }
      catch(error:Error)
      {
         trace("ERROR: CreatePersonCommand::execute, error: " + error);
         finish();
      }
   }
 
   private function createPerson():void
   {
      createPersonService = new RESTFullCreatePersonService();
      createPersonService.addEventListener("success", onCreatePersonSuccess);
      createPersonService.addEventListener("error", onCreatePersonError);
      createPersonService.createPerson(personVOToCreate);
   }
 
   private function onCreatePersonError(event:Event):void
   {
      trace("ERROR: CreatePersonCommand::onCreatePersonError, event: " + event);
      finish();
   }
 
   private function onCreatePersonSuccess(event:Event):void
   {
      // server has successfully created PersonVO, let's update ours with what
      // the server sent back to ensure we now have a proper PersonVO.ID set
      // by the server
      if(createPersonService.savedPersonVO != null)
      {
         personModel.person = createPersonService.savedPersonVO;
         organizationModel.addNewPerson(personModel.person);
      }
      else
      {
         trace("ERROR: CreatePersonCommand::onCreatePersonSuccess failed, server sent back a null savedPersonVO.");
      }
      finish();
   }
 
}

Step #3: Strong Typing

Case: Using loose typing/variants/Objects/*, resulting in loss of compiler time checking and thus errors that only appear at runtime.
Solution: Use strong-typing.
Language: ActionScript

Bad Code:

/*
Notice:
- personVO.lstName is a mispelling, but no error will be raised by the compiler.
- no error will be raised by the updatePerson function as Object is dynamic,
and lastName will be created and set on the personVO Object.
- no error will be raised if you pass something other than a personVO to updatePerson
except for runtime errors
*/
 
var personVO:Object = {};
personVO.firstName = "Jesse";
personVO.lstName = "Warden";
 
function updatePerson(person:*, newNameFromStringBlock:String):void
{
   var nameArray:Array = newNameFromStringBlock.split(" ");
   person.firstName = nameArray[0];
   person.lastName = nameArray[1];
}

Refactored Code:

/*
Notice:
- our "lstName" will be caught by the compiler
- our updatePerson function ensures only a PersonVO is accepted to be operated on. If not,
our compiler will let us know.
*/
 
class PersonVO
{
   public var firstName:String;
   public var lastName:String;
}
 
var personVO:PersonVO = new PersonVO();
personVO.firstName = "Jesse";
personVO.lstName = "Warden";
 
function updatePerson(person:PersonVO, newNameFromStringBlock:String):void
{
   var nameArray:Array = newNameFromStringBlock.split(" ");
   person.firstName = nameArray[0];
   person.lastName = nameArray[1];
}

Case: Service layer has no input validation, is hard to test, and has no error reporting. Burden is on class user to wrap in try/catch as well as parse server response including knowing business logic. Finally, asynchronous loader is not a class member variable, thus potential memory leak + harder to debug.
Solution: Create a Service class that is easy to use, validates inputs, and logs errors. Encapsulates business logic.
Langauge: ActionScript

Bad Code:

class CreatePersonService extends EventDispatcher
{
 
   public var loader:URLLoader;
 
   public function CreatePersonService()
   {
      super();
   }
 
   public function createPerson(person:PersonVO):void
   {
      var loader = new URLLoader();
      loader.addEventListener(Event.COMPLETE, onComplete);
      var req:URLRequest = new URLRequest("http://someserver.com/restful/api/");
      req.data = person.toJSON();
      loader.load(req);
   }
 
   private function onComplete(event:Event):void
   {
      dispatchEvent(new Event("success"));
   }
}
 
var service:CreatePersonService = new CreatePersonService();
service.addEventListener("success", onSuccess);
 
function onSuccess(event:Event):void
{
   var json:Object = JSON.decode(service.loader.data);
   var person:PersonVO = new PersonVO(json.firstName, json.lastName, json.birthdate);
}

Refactored Code:

/*
Note:
- createPerson validates you gave it a valid PersonVO.
- all errors within class are opt-in, no throw's. User has to register event listener to hear; #dontCreateGrenades
- class assumes single-concurrency if possible, kills previous load call before proceeding
- listens for all errors, and responds with 1 error with more detail logged if needed; simplifies API
- wraps actual call to verify SecurityError isn't thrown and if it is, it's logged w/ opt-in error
- uses united tested Factory for DRY parsing and assumes
- assumes Factory can fail, and reports it as such
- result in the form of a strongly-typed ValueObject in a read-only property to ensure proper API usage
*/
class CreatePersonService extends EventDispatcher
{
 
   private var _savedPersonVO:PersonVO;
   private var loader:URLLoader;
 
   public function get savedPersonVO():PersonVO { return _savedPerson; }
 
   public function CreatePersonService()
   {
      super();
   }
 
   public function createPerson(person:PersonVO):void
   {
      _savedPersonVO = null;
 
      if(person == null)
      {
         onError("You cannot pass in a null person to create.");
         return;
      }
 
      if(loader == null)
      {
         loader = new URLLoader();
         loader.addEventListener(IOErrorEvent.IO_ERROR, onIOError);
         loader.addEventListener(SecurityErrorEvent.SECURITY_ERROR, onSecurityError);
         loader.addEventListener(Event.COMPLETE, onComplete);
      }
      else
      {
         try
         {
            loader.close();
         }
         catch(error:Error)
         {
            // only exception that is ok to swallow
         }
      }
 
      try
      {
         var req:URLRequest = new URLRequest("http://someserver.com/restful/api/");
         req.data = person.toJSON();
         loader.load(req);
      }
      catch(error:Error)
      {
         onError("CreatePersonService::createPerson, error: " + error);
      }
   }
 
   private function onIOError(event:IOErrorEvent):void
   {
      onError(event.text);
   }
 
   private function onSecurityError(event:SecurityErrorEvent):void
   {
      onError(event.text);
   }
 
   private function onComplete(event:Event):void
   {
      try
      {
         _savedPersonVO = PersonFactory.parsePersonFromJSON(loader.data);
         if(_savedPersonVO != null)
         {
            dispatchEvent(new Event("success"));
         }
         else
         {
            onError("CreatePersonService::onComplete, factory returned a null PersonVO.");
         }
      }
      catch(error:Error)
      {
         onError("CreatePersonService::onComplete, parsing error: " + error);
      }
   }
 
   private function onError(errorString:String):void
   {
      trace("ERROR: CreatePersonService::onError: " + errorString);
      dispatchEvent(new Event("error"));
   }
}

Step #4: Fine Tuning

If you made it this far, and have managed to continue to maintain the above, congratulations! This stuff is icing on the cake. You can continue onto smaller scope refactorings, as well as continuing to increase your unit test coverage.

Final Tips

1. When casting, ensure result is not null before using. If null, log the casting failure.
2. For Flash Player, set ExternalInterface.marshallExceptions = true if using ExternalInterface
3. Log all errors
4. Code Review. Often. Weekly. Whatever, pick a schedule.
5. Object / * / Dictionary == if you can’t avoid, wrap with unit tests
6. Remember: small, low-risk changes.
7. TODO was invented for a reason.
8. If you haven’t committed to source control for 3 full days of working, abort and just check into a branch for later revisiting/reference.

Conclusions

Remember, the most important refactoring you can possibly do is reading the code base for 1 hour a day, no more. Just 1 person. This is has more positive impact than good unit test coverage. Daily code reviews, even in isolation, are extremely important. The earlier in the project life cycle, the better.

From that, you can make small, low risk changes. Keep track with TODO’s. Breathe, Rome wasn’t fixed in a day, and a pile of rubbish wasn’t fixed in one either.

For further, positive refactorings you can check an older list by Martin Fowler, and this book has a ton of wonderful ones + tests as well. While a Code Review has decreasing value the more people you add in terms of defects found, the ability to learn & make positive suggestions for architecture are wonderful. If you’re alone, use codereview.stackexchange.com.

In the next article I’ll show you how to get help with the above… and permission.

Why P90X?
I’m a programmer who’s a work-a-holic so I sit for 12+ hours a day, 7 days a week. Recently, my part of the tech industry has gone into major upheaval (change is a constant, but this was crazy), and the only thing I can control about it is my well being to adapt to the change. I always found exercise to be a positive outlet; strength training for the frustration when code doesn’t work or a client drives me bonkers, and cardio for keeping my body warm and not achy from sitting so long. My business partner is a meat head and always raves about P90X that he and his wife do together, so I thought I’d give it a try.

Personal/Life Challenges

• I hadn’t worked out in 4 years (used to do strength training + too much cardio 3 times a week). I couldn’t even pass the test they suggest you pass before you start P90X, but I forged ahead anyway. #growl
• I run my own business so even if I only bill for 5 hours in the day, I still work 14. Being in software, you have to constantly research/read/experiment to stay up to date; this isn’t an option, you just have to do it whether you want to or not (most of us do via our short attention spans). I have to do this in addition to everything else required to run a small business (taxes, paperwork, lead generation, dealing with insane clients, etc). As such, time is in short supply, and valuable, for me.
• I have 2 young kids who are spaztastic like me.
• I’m a beer snob. I like trying new beers every few weeks, from light to dark, foreign and domestic. Water weight.
• I’m not attempting to do the P90X diet. I want to, but not for round 1.
• I’m taking zero supplements, nor shakes. While I’ve found positive results from protein bars when I was younger, nothing of the sort here.
• I’m “not 23″, lulz. I’m 32. My metabolism is not what it was at 18 – 24 where I could eat 10 billion things and show nothing.

Results

So what’s positive that’s happened 3 weeks in?

1. I found some “brand new” jeans from 4 years ago that I could fit into (32/32 vs 34/32). I wasn’t really trying to lose weight, just feel better and bulk up. 3 weeks in, though, clearly my beer stocked stomach is showing results.
2. The first week I couldn’t even use weights. Week 3 I’ve maxed out to the 27lb band (red one) for most work outs, falling back to the black one for some of the harder arm/leg exercises. I’m already having to order heavier bands and maybe a few free weights for some of the leg exercises I’d rather use dumbbells for.
3. Week 1 and 2, I couldn’t finish Kenpo X. Today, I did and only did 18 of the 20 reps on 2 of the exercises. Next time, I know for a fact I’ll finish no problem.
4. First time Yoga, I couldn’t do half of the poses. Now, I’m just getting my tail kicked by Warrior 3 and Half-No-One-Is-Supposed-To-Bend-That-Way-Moon. While all my poses aren’t perfect, it’s insane how quickly I got better at doing + holding just 3 weeks in. I’m uber paranoid about hurting myself so am pretty impressed.
5. Anytime a stretch required me to stand, lean to the floor with my hands and touch it, I’d get my hands to my knees. Now I can touch the floor. 2 years of working out on my own I never was able to do that; it shows just how much repetition + following P90X’s lead can really make you more flexible.
6. I only got a heart rate monitor (+ app + connector) 2nd week in, but already it’s a lot easier to keep my heart rate in the zone. Yes, I do try to raise it, but I’m just amazed at how good I feel even in Zone 3 and 4… (yes, was on the floor week 1 and 2 breathing heavily, not moving).
7. I could only do 1 pull up the entire workout week 1. Using the bands + chair combo sometimes, I can do a lot more, improving week to week. I’m still not happy with my current state, but looking at the worksheets, I’ve seriously improved. I thought it’d take 2 months, but apparently it doesn’t.
8. As I slouch a variety of ways, whether at my desk or at Starbucks (other office), my legs will sometimes fall asleep if I get lost in the code. It used to take 15 minutes for an asleep limb to stop being in pain and wake up. Now it takes 15 seconds. I actually made my leg fall asleep on purpose the other day because I thought it was a fluke. That took me 2 1/2 months to get to back when I was working out 3 days a week even with a personal trainer (who cost bling I might add).

…the other positive thing that’s happened, and I didn’t intend for this, is that some of my friends who were doing P90X, unbeknownst to me, have being inspired to bring it more. Others who were on the fence about trying it have said they’d look into it. Two unrelated people have said the same thing: “The DVD’s have been on my shelf, un-opened for awhile… maybe I’ll try it next Monday.”

Remember folks, this scrawny, beer bellied work-a-holic programmer is getting results in 3 weeks in, feels better emotionally, and I’m only doing 80% of my physical best because of my lack of previous fitness + no good diet + 2 year old hugging me during leg squats + 4 year old falling on me during Yoga + her majesty demanding I do more cardio in addition to my regular P90X schedule. I’ve even switched to more wine vs. beer just because I don’t want to ruin this momentum.

Finally, if you’re still not losing enough fat to visibly see a difference, reading this thread on another forum helped a few people I know feel better.

So good luck and continue to bring it!

It took me 4 days to build an Elevator via Box2D in Corona SDK. I wrote the actual code and API for it in about 30 minutes. Getting the physics to work proved way more challenging than I anticipated. I’m still learning the ins and outs of Box2D as it relates to game development, so wanted to report on how I went about it and what I learned.

The following article talks about how I’m using Box2D in my game, the 4 approaches I took to building an elevator, and what I eventually decided upon.

Please keep in mind some of the things below are related to Corona SDK’s implementation of Box2D. Thus, some of the issues and compensation measures I took may not need to be done, nor happen, in other implementations and platforms.

Why An Elevator?

Elevators provide an interesting transition in both games and movies. They also provide easier ways for game developers to unload and load a level, provide a rest for the player, and/or make it easy to provide cut scene dialogue to prepare for the player for an upcoming part. In a lot of horror movies, they actually are the focal point of a lot of scary scenes such as Resident Evil, and also provide a perfect setting for comedic relief such as such as Spiderman 2 and Deep Rising (good ole Ipanema).

One of my favorite easter eggs was from Max Payne was in an elevator. You walk into a shoddy NYC apartment building elevator alone, with the notorious off-kilter 3rd person camera. Combined with the absurd brightness in the elevator’s interior amongst a very noir game, the tell tale “elevator muzak” is playing. If you shoot the overhead speaker, Max utters a smirk filled, 2nd word annunciated “Thank you!“.

Romance, fear, death. In such a confined space clearly only meant for short periods of stay, elevators can force us to view the human condition ever more clearly. Many writers play up the claustrophobia aspect, the lack of control as a metaphor for life taking us where it wills to, or preying on our fear of the unknown when you hear bad things just outside the lift walls.

It also helps players in games get from one floor to another in a controlled manner. Kind of like they do in the real world.

How Does Mine Need to Work?

A game I’m building requires that a character inside a building go up a floor in the building he is in. It’s based on a Brooklyn apartment building that has 13 floors with 12 ft ceilings. The character is on the 12th floor and needs to use the standard elevator. It has a call switch on the outside. You press a button and the elevator will arrive at the floor the button was pressed. You can optionally walk into the elevator and press the up or down buttons for the same effect. The elevator does not move on it’s own, only when a button is pressed. It currently only operates on 2 floors.

Simple, right? Code wise, it was. Here’s the Lua class on Github. The only thing to really note is the goUp, goDown, and tick functions. The goUp and goDown simply set flags so the elevator knows where to go. The tick function handles the actual movement via the game loop. Distance joints, which I’ll cover in a minute, are not powered by motors, so I just increment or decrement the length to move it up or down.

Brief On Box2D

I’ve fully committed to Box2D. That means that a lot of things are handled for me such as gravity, forces, and collisions… basically all the physics code. If you’re not familiar with Box2D, here’s a brief synopsis.

From the site:

Box2D is an open source C++ engine for simulating rigid bodies in 2D. Box2D is developed by Erin Catto…

It’s basically a physics engine for games, although it can be used for other things as well. It’s been ported to a lot of other languages and platforms, such as ActionScript, Dart, and JavaScript.

It’s recently regained popularity because it can ease the creation of Angry Birds like games.

Box2D Constraints

You give up a lot of control when you use Box2D and also have to develop a certain way. For example, all bodies (or things in the world that can bump into each other) default to dynamic. This means they are affected by gravity, which you usually default to 9.8 to simulate the real world.

If you’ve read the Jailbitch tutorials and/or others of it’s ilk, you basically write code like:

thisObject.y += speed;
if(thisObject.y >= theGround.y)
{
	stopFalling();
	thisObject.y = theGround.y;
}

Notice that gravity is applied, by you, on a per object basis. No code, no gravity. No code, no collisions.

This makes building elevators, or “platforms that raise up and down” pretty straightforward. You just increase or decrease the y value of an object. You can detect to see if the character is touching the elevator, and make sure she rises and falls with the platform.

Using Y

In Box2D, all dynamic objects have gravity by default and all the collisions are handled for you. Additionally, how the collisions happen can be tweaked on a per object basis if you like. Things like how heavy something is hitting something soft, the friction, and the bounce. You do not have to write any code for this; it’s just how the world works.

However, making a dynamic object in Box2D rise and fall isn’t as straightforward as you would think. Box2D has a neat feature which allows developers to set a body’s x and y value, and it’ll apply the necessary gravity, forces, and collisions at the next redraw/tick. However, if you want something to move up, you have to treat it JUST like you would in the real world: through force (NSFW).

If I immediately set an apple above my head at a y of 0, it’ll eventually fall on my head. If I want to stay there, I have to keep setting it to 0 using an enter frame/interval/timer… like a juggler. That’s redonk.

Using Forces

Box2D provides, at least in Corona SDK, a variety ways of applying force; as an impulse/jolt as well as force over time. The 2 in particular are body:applyForce and body:applyLinearImpulse.

The applyLinearImpulse is momentary jolt or shove.

The applyForce is like a jet pack; you have to continually apply it via a timer/tick/enter frame to move something.

As you can see, this makes things more complicated. Instead of simply “moving an object by changing it’s y position” you’re now having to compensate for the gravity of t3h erf.

Using Kinematic Bodies

The other simpler option is to utilize kinematic bodies. Instead of dynamic, kinematic allows a body to be affected by forces, like things bumping into it, the functions above, but NOT gravity. Ideal for an elevator, right? In theory yes. I’ll explain why I didn’t end up going this route in a bit. The only drawback here is that kinematic objects don’t “look” like real world objects. They don’t “sway” in the wind, or of something pushes it it just slightly moves. It doesn’t look “real” and defeats the purpose of using Box2D. While following Newton’s Laws of Motion, it looks like an elevator in space vs. on Earth with gravity.

The whole point of kinematic is for the user to drag them via touch or mouse, for cut scene animations where a character can still affect the physical world but you need to move elsewhere… or for things you specifically don’t want to be affected by gravity.

Using Joints

The 3rd option is constructing a realistic elevator so that Box2D can do it’s job: simulate rigid bodies in a 2D space. The mantra I’ve heard repeated by those more experienced in Box2D is keep it simple (or just abandon Box2D and write it yourself… but um… no). Instead of building a real car in Box2D, just build simple geometry (bodies and joints), and let the image of the car itself make the player think it’s real.

An elevator in Box2D terms is basically a box you can walk in and has a cable that attaches the box to a firm ceiling. This means, you create 2 boxes and a joint.

…but what TYPE of joint? And how do you apply it? THAT is what took 4 days.

Version 1: Distance Joint

A distance joint is a line that connects 2 things. You can shorten the line, and like a fishing pole, will reel in the body it’s attached to while it’s dangling below. Perfect for an elevator right?

Bleh.

My first problem was the box was off-kilter. I made it in a C shape so the player could walk in with a wall to the right, and a ceiling to connect the joint too. Being a non-square, however, this made the elevator’s weight distribution un even. It would immediately rotate even if nothing was on it because the weight of the right wall was heavier then the left side with none.

While increasing the friction the elevator had the consistency of velcro, thus ensuring our character wouldn’t fall out, if the player DID walk left, they’d plummet to their death in the elevator shaft, even if you made the shaft just wide enough to fix the box. While you could shrink the shaft and increase Box2D’s sensitivity, it’d sometimes get stuck.

While I could set isFixedRotation to ensure the elevator no longer rotated, and make the distance joint a little more like a rubber band via its frequency and dampingRatio properties, it still didn’t look as cool.

Version 2: Multiple Distance Joints

Most modern elevators nowadays have a variety of attachments beyond a single cable. Magnetic locks with tracks… and usually more than 1 cable. So, I did the same thing and added 2 more cables to compensate.

At first, I was like eureka. But then I hit problems, and was like, no wai!

For some reason, if I changed the length of the first joint to reel in the elevator, AND set the other 2 joints to have the same length… sometimes it didn’t work. Yes, the values would change, but the elevator would just remain stuck. !? I don’t know if this was my code, the Corona simulator, or… Box2D.

At any rate, our intrepid heros can’t run from zombies if an elevator “sometimes works”. While a great plot device, it’s only good if I can control said plot device.

Version 3: Piston Joint

Piston joints are just that: a piston. You can control and constrain their linear movement so moves just like a normal hydraulic piston on carnival rides, etc. Fine, I’ll lose the elevator swaying/dangling behavior, but with piston constraints, it should make the coding easier, right?

Wrong.

Piston constraints, and Box2D in general in Corona totally breaks down when you introduce groups. In HTML, this is div’s within div’s. In Flash, this is Sprites within Sprites. In Corona, Groups are basically the same thing. When creating a game level, you can put the whole thing in a group, and just move the group to move your level.

Box2D, however, doesn’t like this at all. It assumes all bodies are in a same group. While you CAN put things in different groups, things get visually very strange.

Here is some boxes on top of each other.

Now, here’s where I move the group the 2nd box is in. You’ll see boxes pile on top of one another even though visually they are floating in space.

This change of global space also affects calls to the pistons setLimit function. Given Lua in Corona doesn’t have a lot of built in methods to affect coordinate space on the fly, you’re pretty much forced to keep things in a single group to keep it simple. While fine, you still have to CONTINUALLY update the coordinate space… and that doesn’t work if you a lot of classes affecting this as well as the fact that joints can move.

Version 4: Kinematic Floor

I knew I could knock this out in 20 minutes in Flash. So… I coded it like I could code it in Flash: Make a box, decrease its y to move it up, increase its y to move it down. In simple tests, this worked great. Again, I lost the realism factor (the whole point of using Box2D beyond saving a lot of code writing for collisions), but whatever, you MUST git-r-done and move on. Analysis paralysis == bad news bears. Kill t3h scope creep, man.

…however, once I applied collision filters, this fell on it’s face. The same exact code works just fine using a dynamic body, but kinematic? NOoooooOOOOOooo….

Debugging collision filters are impossible; they either work, or they don’t, and your only 2 options are to check your math again or give up. The most frustrating part is that collision filters are the main reason I like using Box2D vs. my own code. When they break (or appear to… no way my math is wrong… ever… specially when I’m changing the body type… right?), they erode to whole purpose of using Box2D in the first place.

I have a rule: if you can’t solve something in an hour, it’s time to move on. Whether that’s another problem/bug/feature, or solution in this case, so be it. So that’s what I did. My #’s checked out, but even in the isolation tests I did, the kinematic box would NOT collide with my character and no collision events were dispatched.

Things got REALLY weird when I created complex bodies using filters for each part; you can see the kruft multiple body code in the elevator class on github. Totally unrelated geometry would act very strange. I’m pretty positive it’s a bug in Ansca’s implementation as I suspect most are merely creating a single polygonal body for complex shapes vs. multiple (like I was for my floor, wall, and elevator ceiling).

Maybe if I spent another hour with a lot of sleep and no kids around I could figure it out, but the rule is there for a reason.

Solution

So I went back to Version 1 and just turned isFixedRotation to true. I also found that sometimes the elevator’s distance joint would get stuck at the top or bottom and even with a high maxMotorForce, the joint was simply incapable of dislodging the elevator. Worse, the values WOULD continue to change and I’d receive no code errors, and visually nothing would change. Simply applying some light applyLinearImpulse (a quick jolt) up or down fixed it every time.

Now, when my character passes by an elevator switch or touches the elevator, the GUI appears for him to go up or down. He’d sometimes fall through the 20 pixel floor, so I increased the Box2D position sensitivity from 8 to 10, slowed down the elevator a tad, and this seemed to fix it. Increasing the Elevator floor’s height + density seemed to help as well.

Conclusions

As you can see, what I thought would be simple was made harder by my not knowing the quirks of Box2D, nor having built an Elevator with floor collisions before. That said, Box2D is really fun, and I can see how the more I learn about it, the more time it saves me for certain types of things… like my Die Hard fire hose.

Basically, the things I need to keep in mind and learned:

1. Keep all Box2D objects in Corona in a single Display Object; inject child dependencies if a class needs to create composited objects
2. If a joint has a length & motor, but things get stuck, try increasing the body’s density, reduce nearby body’s friction, and applying a tincy bit of impulse to “git er unstuck””.
3. Create visual test harnesses; a place where you can test your components in isolation. It’s amazing how frustrating debugging reference points are in Corona SDK as a Flash Developer. In Flash, everything is aligned top left unless you move stuff manually. You can’t even edit the registration point. In Corona, my convention is to default everything to top left to emulate how Flash works, and thus make my visual alignment coding appear cleaner… except for groups. Being able to test the elevator alone, and then in game, allowed me to quickly diagnose problems.
4. To heck with you piston joint. You’re awesome, but until Corona makes it easier for you to adjust being in a different global coordinate space, I’m sticking with distance and touch joints.
5. I really wish I knew why my kinematic bodies aren’t working with my collision filters. In isolated tests, it works just fine.

I hope this helps you in your Box2D adventures.