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.

What is Consulting?

Consulting in the Flash/Flex world usually consists of 3 tasks that may be related:

1. Offer your architecture expertise.
2. Offer your code mechanic expertise.
3. Augment an existing team.

For #1, companies either want you to architect a project, give professional feedback on a suggested/signed off architecture done by another firm (usually to give a stakeholder corroborated evidence), or are having scalability problems and want your advice.

For #2, things aren’t going well and they want you to fix it. No, not re-write it, fix it.

For #3, they want you to augment an existing team. Some firms do this because the pay + finder fee is good money. Other firms do not because you can sometimes be put into situations where you’re setup to fail since you may be smart enough to fix it, but you’re not in charge, thus you cannot do so.

#3 is how I got into consulting, staff augmenting an existing team. While the #1’s were fun, they were few and far between; usually big companies would rather pay lots of money to fix things vs. pay what it costs to do it right. This isn’t cynical, this is fact.

Why Get Into Consulting?

The reason is often simple: more money. More money than full-time/salaried/W2 work. More money than freelance/contracting.

Other reasons include working with really smart developers, learning about how Enterprise companies build & sell software,  learning about how to work in and manage large software teams… TONS of opportunities to just learn on a variety of subjects. Sometimes people havenâ€t worked on extremely large codebaseses. Itâ€s fun to take all the theory and see what it actually does in the real world, with real people.

Me personally, I like travelling, meeting new people, and seeing how different companies work.

Getting Into Consulting

You have a few options listed in order of ease.

1. Find a firm, become an employee.
2. Find a firm, become a sub-contractor.
3. Become an independent contractor.

If you find an existing firm, especially when your country isnâ€t in a recession, this is the easiest way. Whether large like Deloitte and Accenture, to smaller firms (more focused on Flash/Flex) like Roundarch and Universal Mind. Regardless of skill level, while youâ€ll be sold to the client as a “consultant”, but larger firms will ensure a senior is on the project unless youâ€re merely staff augmentation. Joining as an employee usually is easier because youâ€re cheaper tax wise/cost wise to the firm, and youâ€re more versatile to them. Meaning, since youâ€re on payroll, they can pay the same rate to fix a huge clientâ€s code base as well as working on your firms intranet when in between clients.

If youâ€re the freelance type, or typically like getting a variety of clients (and often potentially making more money), becoming a sub-contractor is another option. This is how smaller firms get off the ground, and is common place even in larger firms. While you usually cannot do mundane work, this is often easier for smaller firms tax wise, thus itâ€s an option as well. If the firm has no current clients, you wonâ€t get any work though. A W2 will get paid for the 2 week downtime, you wonâ€t. Hustling during consulting engagements is usually harder than hustling during contracting ones.

If you have enough contacts or typically do only Enterprise type software (LiveCycle, BlazeDS, Java/Spring/Hibernate), then going the independent route is also an option. Basically, start your own company, and start working directly with clients. This is the hardest, even if you do Enterprise software, because most larger clients only work with “companies”. Just because you have a company legally filed on paper doesnâ€t mean youâ€re a “company”. Often theyâ€ll want multiple developers on a whim, liability insurance, and multiple large clients on your track record/portfolio. Iâ€m personally still learning the sales for this, but it seems networking tends to help a lot/the most.

My advice, seek out people you know from the community at Roundarch, Universal Mind, or Cynergy, and make sure youâ€re known to be available, even if they donâ€t currently have any openings.

Skills

Being a consultant involves a lot of things a normal software developer doesn’t do. Even if you’re a salaried/W2 employee, these are still required:

1. leadership
2. large scale architecture
3. travel on-site to client’s location
4. expense reporting
5. meeting clients and their stakeholders
6. offering professional, 3rd party opinions
7. dressing nice
8. attending meetings for a company you don’t work for
9. interviewing/hiring members for your team and/or the company’s on the company’s behalf

All the standard stuff like team management, working with the company’s stakeholders, and tracking your hours are there too. You also donâ€t always do all the above mentioned; sometimes just one. Itâ€s just those arenâ€t normal required in traditional freelancing (excluding #3 and #5). Let’s break down what these skills mean.

Leadership

Unless your role is for staff augmentation, leadership is the most important skill for a consultant. You need to be able to inspire confidence in strangers you’ve just met, inspire confidence in your chosen direction & decisions, and to keep people moving on the right path.

Some leadership skills can be taught. Some people are just born with the other aspects. If you don’t know how to do this, watch & learn from those that do. Examples include raising your Charisma score. Doing one or more of the following will help:

• have good hygiene
• have clean clothes that are ironed
• dress to impress; this boosts your confidence as well. You want to look successful.
• listen: people like good listeners
• empathy: people like others who understand them. If you listen to their pains, and sound like you understand, you connect.
• be knowledgeable: if you know what you’re talking about, you’ll exude confidence when you talk. You also won’t get offended if someone disagrees and will want to hear their point of view. If you don’t know, ask/listen vs. act like you know.
• have a vision: assuming you know the companies problems, have a long term vision to fix everything. Communicating this to your colleague and your clientâ€s employeeâ€s is paramount.
• communication: you need to be an effective communicator to articulate your vision to others, and get them to follow you. Be relaxed, look people in the eyes, be confident in your delivery, and be open to listen. Using slang/ebonics/l33t in normal conversation negatively affects peopleâ€s perception of you. Be professional when you speak.
• egg shells: crush those sons of bitches. You do NOT walk on egg shells. You’re a consultant; grab drama by the neck, raise it high, and execute it. Then, move forward.
• be positive: while Andrew Dice Clay and Rush Limbaugh have gotten popular for their negative spin on things, they don’t last. Positivity is the antithesis to Entropy; that lasts, especially in people’s perception of you.
• control your emotions: software is hard. People in large groups do really dumb things, particularly large companies. Have patience, breathe, and keep your emotions in check.  Your self-control inspires confidence in your actions by others. People assume you have things under control if you’re relaxed and poised.
• win: You have to WANT to win. You need ambition to reach your goals and vision. If you have that, you’ll have the motivation to do all of the above.

Large Scale Architecture

The most common need in the Flex world is architecting how the Flex talks to the BlazeDS/LiveCycle, and how that talks to the Java, and how that talks to the client’s stuff. Often, they’ll have an existing infrastructure in place and you’ll need to decide & describe how and where to integrate technology stacks to a client’s existing infrastructure and possibly already in progress project with the existing resources, which are often in a variety of teams.

You need to know this well enough that you can cater design, development, and deployment techniques to various client needs. You need to be able to effectively articulate these to the client, the team, and ensure the tasks meet the resources currently available; meaning the client can build, deploy, and support what you’re actually suggesting to do. Thatâ€s a lot of traditionally Project Management tasks.

If you don’t know how to architect large Enterprise sized projects, specifically Flex, learn. If the back-end/middle tier isn’t your thing, partner with those who know it. Unlike learning traditional software skills, you can’t really get away with practicing as a consultant. Based on my consulting gigs people can do this all the time if they’re a salaried employee of a large company. So, if you want to get on the fast track to learn, join a consulting firm and get mentored.

Travel On-site to Client

Unless it’s staff aug, most consulting involves travelling on-site to the client’s location(s) to meet the stakeholders and team. This means donning your business casual, booking airfare & hotel, and travelling both on the weekend and during the week. Being responsible by ensuring you have ample lay over time, donâ€t get the last flight out,  arriving to the airport early, and arriving at a client site early to ensure you’ve gotten enough sleep are assumed.

For those with needy significant others and/or young children, this is challenging to do, and will determine if you do higher level consulting or not. This has forcibly paused my career which Iâ€ll defer to a later blog post.

To me, this was one of the draws I have to consulting. I like traveling to new places, meeting new people, and the lifestyle of being on the move. Being on the road is one thing that’s therapeutic to me.

If you don’t have a few thousand in the bank to cover the costs (flight, hotel, fuel, food), the firm you work for will have to front the money. Either way, you have to ensure this is tracked as reimbursed expenses for tax purposes (unless you’re salaried with the firm). The benefit of paying for these things yourself are tax write off opportunities as well as frequent flyer miles with certain airlines.

If you can use expedia.com, drive a car, and find your way around an airport, you’ll be fine. Sometimes you get to meet new people you sit next to on the plane. Yes, there are cool people in coach, but you want to strive to be in first class even if the company will only fund coach. Make sure you use your own miles program vs. the companies if you can. You aren’t paid for your travel time like lawyers, so it’s nice to have some way to offset costs; i.e. being able to work. Trying to type on your laptop in coach is torture vs. first class.

Expense Reporting

A lot of consultants, even if salaried, are required to document their time and expenses. This means documenting, usually in some web based time tracking program. Thus, you need to be aware of how much time you’re spending on tasks, what those tasks were, and how much more you think you’ll do. This can get tricky, too, when you end up in a staff aug position and basically end up running the project. Suddenly you’re holding the ball, and people are wondering why you’re billing time for meetings vs. coding… you can get into really uncomfortable, and extremely irritating and unfair situations. Examples include being the architect & mentoring company employed developers on the project, and when the UAT comes up at the end of an Agile SCRUM Sprint, you show zero User Story points completed, and people in charge question what value youâ€re providing.

If you document well, cya (cover yer arse), and have transparency with the client into what you’re spending your time on by talking to them early and often, you’ll do fine. While they often don’t plan for you to spend a lot of your time in meetings for doing architecture, as long as they’re aware that out of 4 months of billable hours, 2 months were spent helping the client align their processes to ensure they could support the app, ensure the user stories/features in the application were valid, and the design was actually capable of being built… then you’ll at least get paid.

Document your time, be aware of what you’re working on, and what you need to work on. Communicate what you’re doing for the client often.

Meeting the Client and Its Stakeholders

I like meeting new people. I like talking. I like meeting successful people and learning from them. Consulting with companies that desire your expertise teaches you a lot about software that supersedes the construction of it, but how it’s actually consumed and sold. This makes you question a lot of the commonly held beliefs by OOP Purists and other fads touted in the news. It’s awesome. You get to learn how to build software, how to fix it, how to align teams, how to prevent fire drills, why you’d even want to prevent a fire drill, how to compromise amongst silo’d departments, how itâ€s sold… the list goes on and on.

To get things done, and get bigger problems resolved (like using the wrong technology stack/methodologies/processes), youâ€ll have to meet & talk with the big wigs. If you arenâ€t comfortable talking with upper level management, having an MBA helps. If that isnâ€t your thing, find someone who is good at it, and learn. Sometimes these are either A) the only people that can move you forward and/or B) theyâ€ll great at articulating why youâ€re so effâ€d and just need to deal with it.

Bottom line, you can get the REAL story behind why the way things are, and exactly where they are going by talking to project stakeholders vs. the variety of “this is my world at this company” responses youâ€ll get from interviewing employees who arenâ€t Director level or higher.

Offering Professional, 3rd Party Opinions

Often youâ€re firm will be hired for your realm of expertise. Other times, they already have the expertise, whether internal employees or another firm, and just want your opinion as a 3rd party who isnâ€t currently involved nor has stake in the current project. They actually care what youâ€re opinion is and pay for it. This helps them confirm what they already know with an “iron clad” assessment, or perhaps challenging strongly held beliefs in a certain section of the company.

Sometimes these validations, such as:

“Yes, this other consulting firm is billing out a bunch of n00bs to you for $150/hr, and yes, youâ€re internal employee DID in fact build something amazing in 1 week what the 2 n00bs couldnâ€t do in 3 months.”

…lead to consulting engagements. Sometimes confirming what the company already knows builds trust, and thus leads to a longer term engagement.

Other times youâ€re actually hired for a less valued position such as staff augmentation, but youâ€re experience/knowledge ARE in fact beneficial the project. Thus, you need to find a way to ensure those who need to know learn about what you know. If you sucked, you wouldnâ€t be hired for your high price, thus, ensure the client gets value from you via your professional opinions.

Dressing Nice

Iâ€ve mentioned this countless times before. Clothes make the man. Women typically dress to impress other women; in this case, women need to dress to impress the client. Business casual is usually ok, although, the larger the account, the more formal you need to look. In my opinion, you CANNOT be overdressed for an engagement. If someone mentions on the side you donâ€t have to, theyâ€re either threatened, or donâ€t understand the game.

Dress to impress. If you look impressive, you must be impressive. Youâ€re thus apparently successful because youâ€re knowledgeable. This includes accessories such as the car you drive, the bag/briefcase you carry, and the business card you deploy.

Attending Meetings for a Company You Donâ€t Work For

Sometimes, especially if you end up being a shield for the rest of the team, or if you just want to learn about the lay of the land, the players, and all the drama, youâ€ll need to attend company meetings. These are often a waste of time, or things to be avoided at all costs. However, to management, THIS is their transparency to give to stakeholders at some companies. Providing attendance by your firm is often a requirement.

Either way, youâ€re involved in the project, and need to attend the meetings, and sometimes participate. Sometimes you even need to call/create meetings (OMG, the horror!). These are usually to get consensus from the team on an issue that you couldnâ€t do in SCRUM, or resolve drama, or to brainstorm on how to solve some challenging coding issue.

Interviewing/Hiring Members for Your Team and/or the Company’s on the Company’s Behalf

Sometimes youâ€re brought onto a project, and realize you need help. The company looks to you to “build it” or “fix it”; if that means more developers/designers from your firm, so be it, theyâ€ll find the budget. Getting resources can be challenging. At a smaller firm, you may have to have the resources yourself already ready to go. David Ortinau, one of my mentors on this, has helped me create a spreadsheet of people Iâ€ve met over the years. On it, I list out people Iâ€d hire (and who I wonâ€t ever hire), what their speciality is, and what the last rate I got them for was. This is because they are often working for me. Even at my firm, my partners are uber-busy, so I canâ€t immediately assume theyâ€re always available. Obviously theyâ€re my first pick to work with.

If youâ€re with a larger firm, they can often help in 2 ways. First, they can provide you additional consultants if the client has the budget for it. Secondly, they can sometimes provide resources from other firms. This is more challenging because usually the other firm will want their cut of providing a resource. This means, either your firm makes less revenue from that resource, or justifies the lack of serious profit from your dire need…. or both.

Other times, the company is looking to maintain the solution/software you/you and their team has created. This means hiring employees that work for the client. They’re responsibilities include adding features to & maintaining that software. Often, youâ€re the most qualified to hire said employees. Interviewing potential coders is a challenge & learned set of skills in and of itself.

Getting Out of Consulting

A profession that provides a significant amount of money, a huge opportunity to learn, and networking opportunities with new people & companies seems like something you wouldnâ€t ever want to leave, right?

Wrong.

Consulting has a lot of overhead on the soul. This includes the following:

• copious amounts of travel to be on-site wherever the client is. This is time away from your loved ones.
• dealing with incompetence where said incompetence cannot be fired/laid off, yet continues to actively sabotage your project and/or client relationship.
• dealing with politics that theoretically help the companyâ€s stockholders, but ensure the software team is setup to fail
• various implementations of Agile SCRUM that arenâ€t true to the tenets of SCRUM, and thus donâ€t see the benefit of it. A lot of times, this angers everyone involved in the team including the PMâ€s running it, and is just a gross feeling.
• You potentially never “love the code” youâ€re working on.
• The ultimate consulting goal of “leaving the company better than you found it” may potentially be unknowable in how to do so.
• Entropy is scientific fact that all things eventually will return to chaos. Youâ€re constantly fighting this in consulting/leading large teams regarding the code base; this can take an emotional, and spiritual, toll.
• Sometimes, companies pay you lots of money to produce code that never sees the light of day.
• Sometimes, companies pay you lots of money to code in an IDE you loathe on an OS you are unfamiliar with using a framework you hate implementing design patterns you disagree with amongst a team who doesnâ€t understand why youâ€re unhappy with the status quo.
• If things go sour, you can sometimes not get paid, or take awhile to get paid.
• Depending on the team, the complex processes involved on the surface appear to provide no value to the project and prevent developers from actually writing code since they’re in meetings or writing docs instead.

Add to that the paperwork around expenses & taxes, and itâ€s an enough to make anyone want a salaried job. A steady, consistent paycheck with easy taxes. Sometimes way less stress, too.

In most cases Iâ€ve seen a change of scenery, a long vacation, or just a different project is enough to rejuvenate even the most burnt out consultants. Other times a dive back into the W2 world is a great vacation from consulting.

Just be aware there is a huge pay scale difference between consulting and non-Enterprise salaried positions. Just because you take a salaried, full-time position at a large company because they offer comparable money & benefits doesnâ€t mean youâ€ll actually be able to use your consulting skills. There is a lot of power in not working for a company directly. You can get away with telling them off for being incompetent, explaining how to get out of the mess, and theyâ€ll thank you for it. You do that as an employee, you typically get a different reaction, one you donâ€t want.

Bottom line, this can make finding comparable employment & compensation challenging if youâ€re thinking of getting out. From a skill set perspective, usually only start-ups need someone of that caliber, and unless they have known backers, itâ€s hard for them to afford you unless they offer some serious equity.

Conclusions

Consulting is a profitable endeavor, usually involving your skills on larger projects for larger companies. You can work with various teams or simply offer your expertise, perhaps via training. Itâ€s a great opportunity to learn, meet new people, and discover the business of software and the development processes various companies use. The money canâ€t be beat, either. The easiest way to get in is to find an existing firm such as Universal Mind or Deloitte and get hired.

The skills required are more demanding that normal freelance software development. Specifically, knowing how to architect extremely large applications, having good leadership skills, and the ability to communicate complex subjects succinctly are key. These skills can be learned and practiced.

Consulting is a demanding career choice and itâ€s ok to take a break from it. Being an expert in your field requires you to be constantly researching, learning, and being on top of your game.

Keep in mind, too, you can work for a consulting firm and “just code”. This isnâ€t consulting, though.

Introduction

Early in the year, I knew I was done with freelance, and working with other consulting firms. Freelance doesn’t make enough money, and working with other firms prevents you both from doing what you want to do, as well as making more money. I could either build my own firm, which required a ton of branding & marketing work, or just join an existing one. There are pro’s and con’s to each and after weighing the options for about a year, I just joined Web App Solution as a partner for a year to see how it went.

I figured, even without doing a marketing push on my blog, Twitter, and speaking engagements, it was a shoe in to more, larger engagements. My assumptions were WASI already had an existing client base I could tap into, having 3 additional Flex + Blaze/LiveCycle developers associated with me exponentially increased my value to clients, and I could leverage my existing brand to enhance both.

It hasn’t worked out like that at all. The recession from the fall of 2008 is still in full effect. Back in 2006/2007, I’d have 4 clients I’d court, and then pick 1. Getting them to sign a SoW was cake; I wanted them, they wanted me; it was just the formalities on getting a number we could both agree on. Last year, and this year, I’ve lost count of how many clients I’m courting. It’s gotta be in the realm of at least 20 who are worth pursuing, and tons more who aren’t, yet may pay some money in between the larger engagements. That, and my expectations for engagements are higher. As a company, we have a lot of value from a resources, tax benefits, and experience perspective. We can charge more for that value.

Additionally, the type of clientele I target are very different from the clientele I targeted when I was freelance. To summarize, I used to target Flash engagements that lasted 6 weeks or less (often just 2 days). When I got into consulting, the firms I used to work for would usually target engagements, often Flex, that lasted 2 months, 6 months, to 18 months. The 2 month gigs often cost more for the client, but didn’t have a lot of consultants on-site, and thus weren’t very profitable. The 6 month gigs were either small engagements to help a mid-size company get started a project, or more often to save their failing project. The 18 month gigs were often larger enterprises who wanted to create some B2B product, and needed a partner to do so. Meaning, they didn’t the in-house development resources, and thus hired the firm.

My firm targets the same types of 6 and 18 month gigs. To get those kinds of gigs, however, is really hard. Companies are sitting on $2 trillion dollars in the USA, and a lot of the banks have $1 trillion to lend; all aren’t spending/lending it to grow their business because our Congress is trying to pass some new bill to replace the failed Sarbanes/Oxley. The 250+ new rules has them scared, and thus they are holding back doing anything until I they know what our crazy blue gov’t plans to do. The 2000 page document that no one in the Senate has read, has 150 page summaries being sent out to various companies by their lawyers. Yes, I’m aware that “summary” is the incorrect adjective to utilize for “150 pages”, but it is what it is. Also, given my blog word count, I’m aware I’m not at liberty to judge (too harshly anyway).

Thus, I’ve had to work extra hard to ensure the leads (potential customers) I’m dealing with actually have money and can afford my company’s services. Once that’s complete, I have to barrage them with questions to ensure I understand what they need, and my company is in fact what they need. Third, I then have to draft some documents, usually a proposal, to ensure I’ve documented and shown I have a more than adequate understanding of what their company needs my company to build/fix/help them with. Fourth, this needs to be formalized into an SoW that ensures we’re protected, the client is protected, clearly states what the client will get, and ensures we get fairly compensated for what we’re doing. Fifth, we need to close the deal. I don’t want to do any of that, however, unless I’ve ensured the potential customer has any potential, and thus is worth spending time on.

I really really really suck at those things, hence this blog post explaining what I’ve learned and what I think I don’t know, as well as what others have advised I do.

Qualifying Leads

Qualifying leads means ensuring that those who contact you have money, have valid work, and they are worth talking to. Just because someone who emails you for a Flash job has no money, and no valid work doesn’t mean they aren’t worth talking to. I’ve learned a lot about our industry just talking to clients, getting to know them, learning about what they are working on, their perceived challenges, and who they know. These are valuable networking contacts, and sometimes gateways to future work.

That’s the exception to the rule, though. Your gut can quickly tell you if someone over email/the phone is a client you want. While there are a lot of exploratory things you can look for, I only want to know 3 things before I spend any time investing more time than a quick phone call/email reply:

1. How long is the project?
2. Do you have money to fund the project to completion?
3. Am I and/or my company a good fit for the project?

Project Length vs. Sales Cycle

In the past years of doing freelance and consulting, I’ve found you can spend a TON of time on qualifying leads if you’re not careful. While sometimes this leads to good networking contacts, as well as helping your fellow contractors/freelancers pay it forward by referring clients to them if you’re busy, you also lose a lot money. As a freelancer, the only way to make more money is to raise your prices or increase your hours. Freelancers often don’t really have high overhead costs, so you can’t reduce overhead. Thus, time spent talking to clients to get work is time NOT spent working on billable hours.

Incidentally, this is one of the reasons I specifically try not to do any Flash work anymore. The length of those projects, 2 days to 6 weeks, is significantly less than Flex projects which last 2 months to 18 months. Sometimes you actually spend the same amount of time talking to a client to get the ball rolling on the project which significantly cuts into your margins (aka, profit made working on the project minus how much time it took you to get the client to let you start working on the project). If I’m going to spend 2 total weeks courting a client when it only leads to a month of work, that’s pretty costly.

What I’ve noticed is that a lot of Flash freelancers tend to have many clients going on at the same time. The churn and frequency of clients is very high; this offsets their down time. That, and Flash projects have high frequencies of intense activity, and then die off for days at a time, usually as the agency waits for a clients feedback. This works to the Flash freelancer’s advantage to arrange their schedule to make multiple clients work. Additionally, there are federal laws that ensure freelancers can set their own hours (although I’ve yet to meet a client who gives a shit).

Bottom line, you want the shortest sales cycle (time it takes to get the client to sign your contract, or you sign theirs, or both so you can actually start designing/coding) with the longest amount of work. Any downtime between gigs is time you aren’t making money. Charging $200 an hour doesn’t mean much if you only work 3 month out of the year because it’s so hard to find clients who are willing to pay that much. For some people, that’s actually fine.

Do They Have Money?

If a client doesn’t have money, they are usually wasting your time. There are rare cases where a client is actually putting feelers out; this could be a director at a medium to large company, or an Entrepreneur who is doing recon before he talks to his investors. Additionally, it’s not as black as white as having money or not; some don’t have enough, and maybe you can work something out. You need to have a clear idea of what you charge. That topic is too large for this post, but I’ll let you know how I operate for context.

I believe in creating high quality software with a high quality team, and thus charge for that. I don’t compete on price. I don’t lower my price to score a deal because a client thinks I’m expensive. I know what my competitors charge, and I know I’m one of the best, and thus price appropriately. There is a major problem in our industry right now with Flex and Flash work sometimes bleeding into each other. This includes a LOT of factors that muddy the waters, and require a lot of education, re-education, and clarification that you need to do with clients. Some of it is subjective, too, because there are a TON of people who do compete on price right now in our recession, and can give the perception that your points aren’t valid.

“I can go to Best Buy and buy a laptop for $300 right now… why the heck would I buy a $1,500 Mac?”

You don’t see Porche lowering their quality and price just because we’re in a recession. Neither do I.

Regardless, common problems include pricing Flex projects as Flash projects. A lot of programmers have flocked to using Flex and Flash Builder. While 5 years ago, most of us would of used Flash to build a Facebook widget, nowadays a lot will use the Flex SDK. This causes 2 problems. First, you often get high caliber programmers put on low caliber projects that do not utilize their full skill set. Building an Enterprise RIA is most often done utilizing the Flex SDK by software developers. A lot of smaller scale Flash work is now more often more easily done using the Flex SDK, but the price point for such work is still in the low caliber, “quick git-r-done” programmer range. Additionally, the time estimations for such low caliber work are often geared towards a shorter shelf life with consumers often use the tools, not clients who have a feedback channel. Thus, the deadlines, and thus quality of code, are significantly lower because they can be. This leads to extremely short, non-moveable deadlines.

This goes counter to what most Flex Developers who build Enterprise RIA’s are used to; long deadlines, mostly negotiable because of Time & Materials contracts, with good quality code. There are a lot of up and coming Flash Developers who utilize Flex for some of these projects, and thus helps create additional confusion on why one person use the Flex SDK is $30 and hour, and another is $80; when they effectively “doing the same work”. *face palm*

If you are one of those Flash Developers, this is fine. If your’e a Flex Developer, you often have to ensure the client even gets Flex. Most real clients don’t care what technology you use. However, Design Agencies service a completely different clientele than software shops/consulting firms do. As such, you need to ensure the lead on the phone/over email is talking about a “true Flex project”. Otherwise, they are doing a Flash project with Flex, and their rate expectations will reflect this. This means they’ll often be WAY too low than what you were expecting even if they go on about “Flex consuming SOAP web services”.

Another common client I get is the eff’d one. Their developer went AWOL, their team doesn’t know what they are doing and need mentoring, or they are slowly realizing they are getting screwed over by another company and need me to confirm it. If they are a big company, they’ve actually often factored this into the budget, or can easily get these budgets approved very quick. While it sucks that its’ easier to get bling approved to cut your losses than it is to help increase your gains, my consulting career has confirmed this with a lot of large companies. However, every so often I get a company who’s eff’d, or they might not even know they are eff’d, and do NOT have the budget to get themselves out of it. Sometimes they do, but by hiring a $30/hr miracle worker. Consulting in bad situations is bad enough, that’s why you charge for it. Consulting in bad situations where they client cannot afford it are situations I don’t put myself in. While it’s hard to get the true scope of death-incarnate over the phone, it’s pretty easy to get the client’s background and understand if they can fund the rescue operation or not.

Keywords for me include, but are not limited to, the following:

1. 2 week project
2. coder is almost done, but pulled off on another project
3. we’re almost done, but this one feature is killing us, and we’re not sure how to do it (usually means someone who doesn’t know Flash Player capabilities sold their client on something that they couldn’t do, or couldn’t afford)
4. we’re an design agency
5. Flash widget
6. our game is having a few problems

I could go on and on, but all of the above basically mean “we can’t afford your services”. A 2 week project isn’t profitable unless I can ensure 20 of them come in exactly at 2 week intervals, and I don’t spend months trying to line them up this way.

If the coder is almost done, but was pulled off onto another project, it means the company is small, or doesn’t have the resources to tackle larger projects, thus they need you for staff augmentation. I’ve seen a few rare instances where Flex projects have this happen, but pulling the main developer off of a 6 month Flex project isn’t smart at all, and there typically isn’t just 1 Flex developer. Thus, it’s a Flash project, under a deadline, you’re left beholden to that developers’ code, usually not using best practices because the company is more focused on getting it done, on time. Software isn’t done “on time”; if you think it is, you’re not building software, you’re building some short shelf life Flash project for a client on a fixed budget.

The “this last feature we need a heavy hitter on” usually implies either something that shouldn’t have been sold to the client in the first place, or a wrong approach. For the latter, sometimes you can often knock it out in a day, but 4 hours of back and forth with the client for 8 hours of work is extremely unprofitable. This can get worse if you actually do a good job, and they start expecting you to fix their technical debt. While more hours are nice, if you only budgeted a day for the project, it gets complicated to fit into your schedule.

“We’re a design agency” means they’re used to getting Flash contractors for $30 to $50 an hour, thus your software developer rates aren’t going to fly. Worse, most companies/firms charge more for shorter gigs because you have to take resources off of other projects to help the client with their shorter, less flexible project. This has a major cost, and thus you factor that into your price. This, in turn, makes agencies often get a more incredulous look at your price. Bottom line, they want a Flash freelancer, and I’m trying to provide them a resource from my company. Wasn’t meant to be.

Flash widget. I don’t know many Flex coders using Swiz, Continuous Integration, and attempting to master TDD in their SCRUM process who build Flash widgets. Thus, you’re often left with a really small budget, that’s fixed, that’s already coded, on the timeline, and you’re beholden to that alien workflow. Not going to work.

Our “game is having a few problems” is often the worse. Games are actually some of the most challenging things to code. In Enterprise architecture, you often have a long history of patterns and processes to cull from. In games, you have to have good knowledge of algorithms, specific design patterns, and a good breadth of technical understanding of how the Flash Player works. If a client is calling you to help them fix this, they should of called you in the first place. I’ve lost 2 game gigs last year where they ended up calling me back to help them fix it; by then I was deep into a gig, and cursed myself for my lack of sales ability. I don’t like when clients get bit by the obvious, getting what they pay for, but I also don’t like when I would of saved them, but am not given the opportunity to do so. Gaming architecture is often more tightly coupled for performance reasons, and thus is way harder to fix. Combined by the fact most games are done in agencies on fixed budgets with fixed deadlines, it’s just a lose lose situation.

As you can see, making sure leads aren’t looking for a Flash freelancer is hard. Once Flex seeped its way into smaller Flash projects, it made the perception even worse. A larger majority of the “gigs” I’m filtering out are those above. I’m looking more for “engagements”; longer term Flex projects that are for building software for companies.

Is My Company A Good Fit?

The last filter for leads is confirming my company is a good fit. While a client may have settled on Flash, oftentimes I can teach them about Flex and we go the right route. However, if they have their heart set on a custom PHP/Python back-end, it’s more difficult to sell my companies services. My dad would say, “If they ask if you can do PHP, you answer that yes, you can do PHP”. I know PHP, and I’m sure my fellow partners do too, but we specialize in Java. That’s not just a preference, but Java tends to exist in the real of larger Enterprises. There are some, yes, that do PHP… but the clients who provide the longer term Flex gigs use Java. Back in the day, you didn’t invest in Sun servers because they were 10 times what a LAMP stack costs because you were dumb; it’s because it was WAYYYY easier to get Sun/Java consultants than LAMP consultants. If you’ve invested half a million of your company’s money into a project, and no one can help you fix it when it breaks, you’re screwed. Thus, double the budget, and ensure it’s a well known tech that you can hire consultants on in case things go south.

Thus, usually by mentioning something other than Java for the back-end, that’s usually my first indication we won’t end up working together. While both PHP and Java have a lot in common in the open source world, if they’ve invested in a LAMP stack, they are doing so for cost reasons (most anyway). Most large companies I’ve worked with do not care at ALL about cost; they care about making money. If their costs are high, they focus harder on making more money to cover those costs. I’ve seen a lot of good businesses run on LAMP, but they often aren’t the ones financing long term Flex projects. Thus, middle-tier technology choice is often my first clue.

Another is vibe. Does the client sound like someone I’d want to work with? In freelancing, you can be way more forgiving. If the client yells at the designer in front of you and makes her cry, you can usually hold your tongue, knowing you won’t have to work for that mean person anymore who doesn’t respect women in 2 weeks because you’ll be done. For Flex projects that tend to last months, even a year; you’re basically entering a long term relationship. You really need to ensure you both have the same set, or at least mostly common, beliefs. If the client is more interested in getting it done than doing it right, I actually respect this because they believe in making money. Clearly they respect the craft because they are still talking to someone like me who believes in finding that middle ground. Now, keep in mind Jesse Warden is focused on quality first, money second. Others are focused on money first, quality second. It seems trivial, but when this forms the basis of your belief structure, you can get widely different responses on what client is worth forming a relationship with.

For example, if I can tell it’s going to be a staff augmentation job where you’re placed inside a huge company who doesn’t mind if you produce nothing of value for 9 months, most rational company owners would definitely move forward, and ensure more developers could be put on the project. Once you take your cut, you ensure a significant amount of revenue flows your way, AND the risks are low; win win.

Not for me. I don’t want to spend 18 months of my life producing no value for my clients. I didn’t invest 10 years of my life, 18 hours a day, every day honing my craft only to waste it warming a chair, judging the previous vendor’s code base and doing nothing to change it.

That said, I’ve had to lower my idealistic expectations a bit. A lot of large companies who fund the engagements I want to be on often DO want me to produce value for them, they just don’t know how, and it’s just REALLY hard to get message across over a phone call. That, and some of these larger companies don’t run as a dictatorship, and it’s harder to get things done in a democracy.

My dad the salesmen says, “You need to ask them questions.” I’ve taken this a step further and asked them the same questions twice. This can give me insight into their true motives. Some clients really want you to come there, make bling, and help them create awesome software. Others want me to work for free, or at least do the discovery phase for free. The challenge I have is discerning between what the client needs to be educated about, and what they truly believe, and where we can meet in the middle to form a working relationship.

I’m still not sure what’s a good fit, but so far my criteria of ensuring they having money, paying for the discovery phase, and signing Time & Materials contracts is good enough so far; weeds out 90% of the non-valid ones.

Conclusions

I’ve got the initial pitch down. I listen, and ask a ton of questions.

The guys I work with are better at the above than I am. They are, slowly, working with me to better understand who I should focus on, how, and how their SoW formulation process works (because mine clearly doesn’t scale to the Enterprise).

However, because of my personal brand and my vast network, I have an easier time of getting a plethora of leads. Sometimes a hand off isn’t practical, and I need to feel them out directly. Sending a bunch of $30/hr, 2 week, Flash gigs to my partners is just a waste of time. I end up doing a lot of legwork talking to clients, feeling them out, and qualifying them as potential customers. I’ve still got a lot to learn, and feel like a budding AS1 developer.

Another thing that’s extremely frustrating is that my personal brand right now does NOT reflect the clientele I want at all. The honest, edgy, and high strung Jesse Warden is not what Enterprise clients are used to. I’d argue that’s what you need to get anything done there. Once I’m in these companies I can work my magic. The problem is, I’m seen as the medicine they don’t want to take. I’ve had 2 different salesman from a former consulting exclaim how they’d love to have me on a project, but they don’t see how I’d fit. They’ve never seen me on-site with a client, in business attire, having a calm meeting with them working through their issues. What they see is me at conferences rousing with my fellows in the industry, speaking at conferences being “me”, and giving honest accounts of how I do things.

That works great in the freelance game, and even in the consulting firm game, but not in the “I’m my own company” game. Leads keep coming to “jessewarden.com” and contacting me as Jesse Warden vs. webappsolution.com and contacting me as WASI. We’re in a huge rebranding effort right now which I believe will help. Still, it’s effing frustrating.

Tom Link from Universal Mind once told me:

“You don’t hire Schematic to get Schematic; you hire Schematic to get Danny Patterson. Just because you hired Schematic doesn’t mean you get Danny Patterson”.

I’m not sure if it was Danny Patterson or not, but that’s not the point; the point is, I know I’m sitting on a gold mine with my brand, but I’m not sure how to leverage it to make more bling. Many people have been very forthcoming with advice, but none of it seems to work, or I’m just doing it wrong. Many businessman who already make money in Flash/Flex without coding in Flash/Flex, and getting others to code for them, have told me I could be infinitely more rich than they were if I just leveraged my name to bring in business. I’m not ready to do a marketing blitz on WASI just yet; we’re not ready, but I’m not sure what it would do if I did?

At this point, I’d argue that I could only do that doing Agency work because right now, all the Flex clients are either in Manhatttan’s financial sector, or through the magical, and elusive Adobe Professional Services gateway. If I want those types of clients, I’ll have to start watching my mouth, redesign the format of my blog, and start playing the game differently; “clean up my act” as it were. I’m not yet convinced I need to do that.

However, I’m a little frustrated I’ve spent years curating (buzzword bingo, WIN!) my personal brand only to have it cap out at some dollar amount. Eff that. I recognize if I want to make bling, I’ll eventually have to stop coding, and get others to code for me. Fine… but right now, I can’t seem to score the bigger clients. I know we’re in a recession, and even if the big clients have money, they won’t spend it. Those who typically just get a loan now, can’t. I get it, I really do; I recognize I need to use context in understanding the current economic climate and it’s affect on rates, and frequency of work. Our client sales cycles have tripled in the last 2 years because of it. Clients still are signing, it’s just taking longer.

That said, people still buy Porches during the recession. I just want to know how to get them and stop wasting my time with these damn recruiters that never give me anything of value, nor these small potatoes Flash gigs. My dad gets mad when I ask him advice for this, and threatens to start working for me. I don’t work with family. However, at this point, I’m uber close to start focusing 50% of my attention on hiring a salesman, because this is ridiculous. Maybe it isn’t ridiculous, and it’ll soon be great, it just sucks now cause I suck at it. People on Twitter have suggested I’m great at scoring the lead + the initial conversations, I just need to hire a closer. :: shrugs ::

When brought into existing projects in a consulting role, there will often be the perception the project is “mostly done”, or “90% there”.  Opening up the hood, you sigh.  You marvel at the wonders of modern programming technology, how they’ve empowered even the shoddiest, hastily thrown together, duct taped to work and work well, fooling many into a sense of functional complacency.  You also wonder when, not if, it’ll explode in someone’s face.

A lot of short lived software written for conferences and trade shows can get away with this.  It just needs to work long enough to work once or twice.  After that, who cares.  In longer term products & services for companies, most software follows the traditional rule of living 3 times longer than it’s intended life span.  In consulting, you’re brought on to finish it, fix it, and prep her for long term maintenance, hell, maybe even adding additional features to it.

Sometimes you and your team can inadvertently become a victim of their own success.  Once you’ve wrangled the problem areas of the code into a stable state, earned trust with your client, things start to settle down.  At this point in the project, the code really does work as advertised, or you’ve merely stopped all the noticeable and constant explosions.  The land-mines, or unexpected breakages haven’t occurred in awhile to remind people, in a sad way, you still have a lot more work to do.

Introduction

This post assumes you’re a consultant brought in to fix and help release an existing code base.  The client needs to release, and you didn’t write the original code base, yet now are responsible for it’s architecture & direction.  The perception is, either because of your efforts or merely because there haven’t been any explosions lately, the code works just fine and just needs maintenance to get them to launch.  Then, something horrible happens.  The code doesn’t work, and NO ONE knows why.  Suddenly mass insecurity sets in since the reality people thought they knew doesn’t exist anymore.

As an architect who didn’t architect the code, you may not be able to immediately remove that insecurity, but you CAN use it to your advantage.  This post will show you how via defining what fire drills, crises, and land-mines in code are.  It’ll also show you how to prevent them by using diagnostic tools, some of which you’ll have to write.  A lot of these can proactively   Doing this will better equip you to prevent the code from not working suddenly, identify with confidence WHY it’s not working, and help build the team’s trust in your word.

What are Fire Drills and Crises?

A Fire Drill is a slang phrase used in corporate culture.  It’s used to refer to situations where a manager/leader has a perceived importance of something that really isn’t, and demands an individual or team work on it.  This work that comes up suddenly is chaotic, and in the end often accomplishes nothing.  In terms of software, this often happens when a feature suddenly needs to be implemented in an extremely short time frame.  This bypasses the traditional processes used by the team (Waterfall/Scrum), causing much commotion, and often damaging the code base short term and long term.  The more common ones, though, are when un-announced demo’s are given by high level executives, a key feature doesn’t work, and suddenly something the team had been working 6 weeks on to get done now must be done in 1 day.  Complete bullshit, I know, but it happens all the time.

Crises are very similar, although, valid.  In a fire drill, the executives may not know that a newer production build fixes the key feature they wanted to demo, and a miscommunication just happened.  In a crisis, everyone, including the developers, is under the delusion the feature actually works, and in a key demo, it does not.  THAT’s a crisis.  Fire drills, while perceived as important, aren’t.  Crisis ARE important.  Your code doesn’t work… or worse, your code doesn’t work, it’s live on production, and customers are flooding your call center.

Both can cause harm to the code, team morale, and trust in you as a consultant.

Preventing Fire Drills & Crises

A lot of fire drills can be prevented by good communication.  As a developer, you’re primary job is to kick some ass writing code, not give directors and executives transparency into the project; that’s the Project Manager’s job.  As a consultant/architect, however, there is a LOT you can do to help empower the managers, PM’s, and testers with insight into the application, and good information on what’s happening.

If a PM knows what’s wrong with the application, they can confidently assuage the fears of those wondering why things are broke.  The more information they have, the easier it is to articulate the problem.  Sometimes it’s a reoccurring problem.  The confidence, and perhaps slight indifference. in their voice when communicating to those above arising from this commonality will go far in ensuring people in charge don’t freak out.

Sometimes, a PM or tester will know before YOU do.  This proactive action in both known, and new unknown problems, allows you to not only prevent higher ups from seeing problems before they happen, but also allow you to leverage the entire team in debugging your application.  It’s one thing to have a developer and a PM duplicate a problem; it’s another when you have 5 people all getting the same results, with logs to confidently prove it.

During a crisis, a lot of fear is because of the unknown surrounding the situation.  Why is this happening?  Who’s responsible?  Is it my fault, the back-end, or our 3rd party data provider?  The worst thing anyone can do in a crisis is panic.  You need to be calm, collected, and strategize how to diagnose the problem to inform those in charge, and then allow yourself time to actually attempt to fix the problem.

That’s easier said then done when the suits have a gun to you and your PM’s head… and perhaps you even LIKE your PM.  Maybe you feel like the performance of the application is directly tied to team member’s perception of your ability, and helping them determine whether they like you or not?  Perhaps you’re right? ZOMG!!!

Your application needs to talk.  Your application needs to report what is going on with the various aspects of itself.  It needs to tell the truth, or the truth of what it thinks it knows.  You need to have external tools at your disposal to corroborate the application’s built in reporting and diagnostic tools.  These can be off the shelf, open source, and ones you’ve built yourself specifically tailored to the application at hand.  These need to be quickly & easily accessible, and require little to no maintenance.  They need to be relatively easy to use and understanding by not just developers.  Reports generated need to be easily portable text.

These reports and tools allow proactive action against problems, help empower management with good information, and help prevent fire drills and reduce the severity of crisis situations, often preventing them.

Reporting & Logging

How do you get this information?  You’re application needs to talk to not just you, but anyone who asks.  It needs to have a semblance of an agreed upon vocabulary.  It needs to generate fine grained reports about volatile areas.

How do you get it to do that?

Logging.  Logging is another way to say “trace” in Flash or Flex.  It’s a lot more than just tracing out simple messages, though.  You need a formalized way to send them as well as allow them to be readable when you have thousands of lines of messages.  Here is some criteria of a helpful logging strategy:

1. Shouldn’t require any fragile or complicated configuration to get it working
2. should fall back to Flash Player’s trace command so it works with the traditional Flash & mxmlc debug players
3. should have special GUI created around the log messages to display, filter, and allow extraction
4. the GUI should be in the application itself.  This allows anyone to access it easily.  For widgets and small screens, if you’re showing a GUI, you clearly have enough room to show log messages.
5. the GUI should be able to be opened & closed easily from within the application.  Right click is usually the most unobtrusive, and easily removed for production code.  Closing should not remove the log messages from memory, nor affect the logs in any adverse way.
6. The log messages should be able to be easily extracted, copied, and pasted.
7. The log messages should have built in, cross platform formatting to make them readable when pasted into email, text messages, and text files.
8. You should be able to scroll through older messages without being interrupted by the logger.
9. The log window should not adversely affect the application (in Flex 1, override Object.toString() is what some debuggers did, and this broke Flex’ String formatters and validators… but ONLY when the log window was running).
10. Bonus points: per developer filtering, easy to turn on/off, color coded messages, and works in multiple compilers/IDE’s.

Wow… more than just a simple trace in the Output window, ya?  Why all the guidelines?  Let’s break it down.

Stay on Target…

During a crisis, stress levels are high.  You want to make it as simple as possible to quickly get logs from your application.  This shouldn’t have to make you think or concentrate hard on getting it to work; it should just work.  In the case it DOES screw up, or another developer doesn’t have/refuses to have your custom setup, as long as all of your special trace commands still output a trace command, you can utilize the existing debuggers in Flex/Flash.

When Things Breaks, Look Here for Answers

The special GUI is important.  This clearly delineates where log messages go, how you interact with them, and is the gateway for non-developers into the app when something goes wrong.  They will turn to this window when something breaks or doesn’t work correctly.  This is the information they will be combing through for insight into why something broke.  Sometimes this information is so helpful, it’s self-correcting, and you’ll never hear about their problems.  Examples include clearly stating you don’t have a session, and thus the user needs to log back in.  If you haven’t captured all session errors in your application’s Service layer yet, the PM/tester can re-login and try again.  This, as opposed to the 3 email conversation, or the 1 minute phone call all to “just re-login dude…. you’re session is probably expired”.  Doesn’t interrupt your focus, and ensures when problems do arise, those working with you know where to look.

Filter Out the Noise

As your application grows, both in size of code and developers, so to will the frequency of messages.  Sometimes all of those messages are an important indication & insight into the health of your application.  Thus, you need an easy way to filter out the good ones from the bad ones.  This is where a simple trace won’t do.  You cannot differentiate once trace from another easily since it’s just text.  No, using RegEx and clever time stamps doesn’t count.  You need to create messages, a Value Object class that represents the message, the time it occurred, who sent it, where it came from, what it’s saying, and it’s type… at a minimum.  You can go overboard here if you want, but just be aware of the old adage, more code == more problems.  You want to make sure you’re only adding what you need, you don’t make the logging API a pain to use for the developers, and you don’t have to debug your logger for more than a day to ensure it’s not lying to you, or broken.

Filters can include differentiating between logs, warnings, and explosions… also known as errors.  This allows anyone to see the entire state of the app, or just the problems, known and unknown.  As multiple developers get on the project, you’ll sometimes get log messages you didn’t know about; this can sometimes make it easier or harder for you to debug your own issues.  These should be filterable as well, whether at compile time or runtime.  This, too, should be easy to configure.

Portability & Ease of Use

Many debug windows in the Flash community are external.  There are a few advantages of this, namely it makes it easy to debug applications running in a browser.  You’re application isn’t affected, nor necessarily tied to the browser’s state.  Other times, it’s completely separate from your code base, making integration cleaner.  Finally, it’s easy to debug multiple applications using the same debug window.

I’ve found, though, in consulting & contracting over the years, these never work with PM’s and testers as well as custom, home grown, in-application ones do.  Installing and confirming things like Thunderbolt or DeMonsterDebugger work are challenging endeavors unto themselves requiring 3 technologies.  This vs. “just run the app”.  The last thing you need Firefox to wig out on you during a production push, it does, and suddenly you have zero insight into why your application isn’t working on your staging server… and people are freaking out because you’ll miss your production push.

The other nice thing is no matter where your application runs, so to will your logger run.  This includes on your local box, your local web server, your QA server, and even production if you’re your so inclined… no configuration needed.  Nothing like adding confidence to your code base.

This also means ANYONE using the application, from testers to PM’s to suits and bobs in a board meeting; if something goes wrong, you can quickly diagnose what it is without needing the Flash Debug Player installed.

Copy Pasta

Adding just a simple “Add to Clipboard” button goes a long way to making it easier for others to get errors to you when problems occur.  If you’ve ever tried to copy and paste in Flash with it’s awesome focus-fun, you know what I’m talking about.

Moveable & Capable of Being Closed or Hidden

The log window needs to be moveable and capable of being hidden.  Some applications have buttons in certain places and you don’t want the log window to get in the way.  A lot of times it’s just easier to close/hide it.  Whether you visible false it, or just removeChild, whatever works.  This should NOT affect the log messages.  You should still be able to get log messages.  This means that the logger class usually has no GUI, and the log window has knowledge of how to display those messages.  That way, you can kill the GUI, and the messages are still being retained.  More importantly, before Flash/Flex has even started, in the case of static initializer methods (which even the Flash IDE can’t debug), you can still get log information about them.

This should be easy to do.  Usually making it “look” like a window is enough for most people to try to drag it.  Using useHandCursor and buttonMode to true on the top part will show the pointy hand.  Although the wrong gesture, it’s better than the cursor b/c it gives a hint the user can “do something with this part”.

In Flex, it’s easiest to just use PopUpManager.  This puts your logger on top of everything, and if you kill it, you don’t affect other View’s.  Bonus points if she remembers where you dragged it when it opens back up (hint: local SharedObject).

Log Message Formatting

Log messaging formatting is very much opinion.  Thus, using standard formatting options such as newline (“\n”) and tab (“\t”) will ensure whatever your team decides on, it’ll work no matter where it’s copy pasta’d from.  One convention I use to prevent needing strange metadata in your code is the following:

• have log, debug, info, warn, error, and fatal messages
• color code them in the GUI with filters
• all log messages start with “ClassName::methodName” where ClassName is the name of the class you are in, and methodName is the current method the log message is in.  It seems a major pain at first, but I guarantee you when you start removing them 2 months later, you know EXACTLY where to find it vs. that one trace that stays there for weeks because no one found where the bastard is.  It’s not that they couldn’t do a search/grep for Debug.log(, but they’d find 500 of his friends… so not worth the effort.
• I provide a header method for each type of message; logHeader, debugHeader, infoHeader, warnHeader, errorHeader, and fatalHeader.  These are usually just “———————” color coded.  When you put multiple logs in a method, especially for/while loops, this helps visually break up the hundreds of lines of log messages.  This also enforces consistency amongst the team when other members will just use their own like “>>>>>>>>>” and “**************”, and it becomes cool from an artistic ASCII perspective, but a pain from a debugging standpoint.

Writing Log Message Types

You need helpful log messages that aren’t written in g33k talk.  It’s not just you that will be reading them, but testers and PM’s from a variety of backgrounds.  You also need to write clear enough that if a bug crops up 3 months later, you’ve written a message that clearly identifies the problem.  Trust me, you’ll forget as you focus on other things.  Even if you don’t, a confidently written message goes a long way in assuaging people’s fears that you know what is wrong, and got it covered.  Here, I’ll cover the 6 message types, and where & why you’d use them.

LOG

Logs are used for common stuff that is integral the app, and always runs every time you run the application.  This includes loading external service definitions, logging into the application, and other integral data your application needs to get from an external place before it runs.  Logs should get cliche over time in larger applications; you should only start worrying when you don’t see them, and instead see errors.  This, also, is a great indication that something totally wrong… is wrong.

Logs are checklist items to ensure your application is in working condition, or to confirm an action did in fact happen successfully.

Debug.log(“ServiceLoader::onComplete, we’ve successfully loaded our services.xml, and we’re ready to rock this mic!”);

DEBUG

Debug messages are your primary source of insight into new code.  These are messages you’ll put into new code to ensure it works… or into old code that’s acting up.  If you use Test Driven Developement and/or unit tests, these messages are used in tandem to be iron-clad sure that the things you think are happening are actually happening.

Debug.debugHeader();
Debug.debug(“Alright… my method is actually running… amazing, I’m not fired.”);

INFO

Info messages are used in strange, insecure situations.  When something happens you won’t to know about, but doesn’t adversely affect the application, you use an info message.  They can also be used in tandem with debug messages.  If you have a lot of debug messages, it’s sometimes hard to filter them alone, so you throw an info message into the middle to confirm/deny what you were testing/debugging.

Debug.info(“Dude, I didn’t get a security error this time!”);

WARN

Warning messages are used to report errors that don’t negatively affect the continued operation of your application.  These include security errors when loading images, failure to save a file, or when a web service goes awol.  These can lead to, or hint at, bigger problems but sometimes occur so often they don’t hurt anyone, you and your team just need to be aware they happened.

Debug.warn(“LoginService::onResult, succeeded logging in, but I’m getting yelled at to change my password, and we don’t have the popup wired in here yet.”);

ERROR

Error’s are usually a blanket message for all errors.  These include synchronous, asynchronous, and custom problems that arise.  You’ll often log these within try/catch blocks, asynchronous error event handlers, or when your code is expecting something to be true, and it’s not, and you’re screwed because it’s not.  Sometimes you’ll just use a warning instead because you don’t care right now, or it’s not your fault, or you just can’t do anything about it.  Errors usually imply something needs to be, and can be, fixed.

Examples:

try
{
        fileStream.writeObject(obj);
}
catch(ioError:Error)
{
        Debug.error("FileSaver::onSave, Couldn't save the file, ioError: " + ioError);
}

function onIOError(event:IOErrorEvent):void
{
        Debug.error("FileSaver::onSave, Couldn't save the file, ioError: " + ioError);
}

FATAL

You shouldn’t have to ever use these.  You’ll find that WARN and ERROR messages on their own cause concern amongst the non-developers on your team.  Even messages written with a concerned tone using LOG/DEBUG/INFO can arouse suspicion, and fill your inbox unnecessarily.  You should only also NEVER write fatal messages when you’re emotional, like when a 3rd party web service breaks for the umpteenth billionth time, and it’s not your fault… yet your team always gets blamed.  Maybe the code isn’t in a solid enough place yet to actually debug it.

Fatal’s should really be saved for situations in which you’re royally screwed.  If you fail to save a file, and you’re app is built a Notepad like app… you’re pretty screwed, but you’re not royally f’ed… there is a big difference.  Maybe the user is out of hard drive space, or the file is locked.  If you can’t recover from an error, but perhaps can wait it out, you still have a chance.

If your external services.xml file doesn’t load, and thus you’re entire app doesn’t work?  Yeah, that’s a fatal message.

More on Messages

Litter your application with these, but only the ones you need.  Sorting through hundreds of messages to solve a simple null pointer exception is painful; don’t make your job harder than it has to be… but don’t skimp on helpful details either.  It’s an art, and you’ll get better over time.  Sometimes your messages will be great for 6 weeks… and then after that section of code base always works, you can comment them out.

Finally, try to be proactive with errors & warnings.  If something breaks, and you have an idea, provide insight into perhaps why.  Examples include ExternalInterface.call or stage.displayState == “fullscreen”.  Both can fail because the HTML/JavaScript embedding them didn’t have the proper parameters set.  You can explain what these are.  Even if that isn’t the problem, knowing they are gone usually hints that perhaps the html-template in Flex Builder got messed up during a merge, or perhaps the wrong HTML was pushed to the server, etc.  These are really nice when they popup months later, and you immediately go, “I’ve never seen this message before… we clearly did something out of the ordinary.”.

Finally, keep in mind you should try not to push debug messages to your staging & production servers.  You need at least 2 servers without messages in case they negatively affect things.  Accessing objects inside of a debug message itself can cause a null pointer for example.  Also, trace is basically a write to the disk in some situations, and slows your app down.  While removing the messages and speeding your app up may seem like a good thing, sometimes strange race conditions your debugger fixed will arise.  Better to see them before you move to production.

Reporting

Logging is a form of reporting, but reports specifically are run on certain sections of the code base and data to get finer grained information, and ONLY on that section.  Sometimes you can write a unit test to get the report you want, or other times just a custom class/application.  Examples include validating, en masse, all data coming from your back-end is valid.  On my current project, I loop through 500 videos and ensure they play within 10 minutes; all I do is hit a URL in the browser and it runs.  It prints out custom log information on the status so I know clearly what’s going on. It’s ONLY for that particular report, so I don’t need to do any filtering.

Reports can be run in specific SWF’s tailor made specifically to run them.  Making these easily accessible to others allows increased insight to various parts of the application.  Example:

“Jesse, the application isn’t displaying images from the image server again.”

“How do you know it’s the image server that’s failing?”

“You’re debug window said it was.”

“Did you run the image server tester app?”

“Yes, and it confirmed that our internal development image server works, but when we he hit the production 3rd party one, it fails, so it’s definitely their fault again, not ours.  I’ve already told the build master to switch to our local server for our noon demo until the 3rd party can get their act together.  Just wanted to let you know if you start getting old images.”

Within seconds, someone from your team can run a SWF that ISN’T your application, and determine it’s not the application that’s broken.  Sometimes, applications take awhile to run, as well as awhile to navigate to the problem section you want to test.  If the problem occurs repeatedly, you make it dead simple to diagnose by all.  Win.

Using these reports in tandem with other data allows PM’s to place pressure where they need to, with the team’s confidence behind them.

Other Examples of Fire Drill & Crisis Prevention

This crap happens to me ALL the time.  An IM pops up:

“Dude, the app isn’t showing any data!!!!”

“I know.  I already told our boss.  It’s not our fault, it’s the server team having migration issues.  They’ll have it up in about 10 minutes working again.”

“Whoa… that was quick.”

That, vs. panicking, and then you have to run the app.  This assumes you aren’t in the middle of something and the app can even compile.  Within seconds, you clearly identified the problem, informed the necessary parties, and set the team at ease.  That as opposed to a fire drill which breaks team focus.  As we know, developer focus is EXTREMELY valuable to maintain.

Another is:

“Jesse, Java middle tier dev here.  We’re not seeing video’s work here, but a quick test in the browser shows they are coming from Amazon’s CDN no problem.  I didn’t want to spend an hour running scripts to sort through failed video FTP logs, so was curious if you knew of anything before I did so?”

“Huh?”

:: runs video tester ::

“Hrm… works in the tester; you checking production?”

“Yep.”

“Ugh… hold on, lemme test….”

:: tests ::

“Yep, my code broke it… I’m getting error messages from a totally different server in the app itself.  Give me an hour, I’ll push a new build.”

“Thanks!”

First, I saved a middle tier developer’s time.  Second, I quickly ascertained the core video services worked; it’s just my latest code change broke it.  This WITHOUT having to resort to a debugging session, or even comparing tagged builds in SVN.

More on Video Diagnosis

I use video diagnosis as an example reporting application merely because streaming video is really complicated.  There are a lot of failure points, and it helps to know which point failed.  Without verbose logging, it’s hard to tell what the error really was.  In dealing with 3rd party CDN’s, they will NOT respond to you unless you can easily point the finger.  Thus, you need verbose coverage of errors to effectively communicate all bases on your side are covered.

For example, does the NetConnection work?  If one of his 7 failures, excluding the 10 billion ones you have manually parse (yes, PARSE) out of NetStatus, do you know which one failed, and why?  What about NetStream?  Are they failing because of your session?  Your token?  A malformed URL that botched the whole process?

This is where a complex section of code is better tested in isolation.  Unit tests help here, yes, but a lot of times you need to run a lot of stateful code that gets way too complex to test in just 1 unit test.  That, and you verbose reporting data, in order.  Data that you can send to those in charge and CDN’s for help tickets.

Having a simple Flex app that plays a bunch of videos and reports verbosely on their successes and failures is invaluable without having to:

1. run the app (assuming it complies, and assuming it’s working on a specific server where the problem is reported)
2. login
3. navigate to section
4. select video play

…slow!  If you do this more than 2 times, you’ll probably be doing it a lot more.  Things that are complex break more often, thus having diagnostic tools around them helps you more quickly ascertain the problem.  Remember, while unit tests specific units of code, diagnostic tools test application functionality.  While you can write unit tests to do this, writing a simple GUI anyone can run quickly to see if something works is invaluable.

Service Layer Diagnostic Tools

For most services (web service, REST, SOAP, Remoting, etc), unit tests will suffice.  If you can quickly test 30 web services, and see that not only do they work, but the data they are sending back is valid, it’s really nice to blame the middle tier guys & gals so you can get back to work.  It’s always easy to blame the client because that is the main GUI used to access & use the services.  Granted, the middle tier developers can access your unit tests as well, but sometimes it’s helpful to provide a GUI for them to quickly test as well.  This includes customizable parameters that can be sent with verbose logs that ensure you’re code is sending & getting what it needs.  Trust me, the more empowered your middle tier developers are, the better off you’ll be in the long run.

Tools you don’t have to build here include Firebug for Firefox, Charles HTTP Proxy, and Wireshark.  All work right now, and all aren’t your code.

Some tools are built upon a specific service.  For example, one project we were showing a bunch of images for a certain account.  Each account had certain images show on certain dates & times.  It was INTEGRAL that the GUI correctly represented this.  Since there were a lot of failure points, I created a simple GUI to easily validate that the data I had not only was visually valid for the middle tier developer to confirm in the database, but also matched our applications use of the data.  It was just a simple DataGrid, in a TileWindow, with 1 custom itemRenderer.  However, that one component found sooooo many bugs, and really gave us a lot of confidence our back-end was working as it should… and my parsing code blew chunks.

Performance Diagnostic Tools

While Flex Builder comes with a profiler, you can create your own profilers as well.  You can access the sampler classes, and/or make your own profiling tools to constantly update you (or manually) on the current performance of your application.  As RIA’s tend to push a lot of browser based app limits, it helps to know just how far you are really pushing things.

Existing tools include Stats, which making accessible via right click menu is awesome.  Also, Grant Skinner’s PerformanceTest.  Getting familiar with how Flex’s profiler works, at least for memory, is a wonderful start.

More on Tools

Most diagnostic tools I create are simple, quick, and exist in a self-contained window visually, and package in the code base.  This ensures the code is easily removed if it causes a problem, it has a low risk of causing a dependency, and I can easily work on the tool in relative isolation.  I ONLY create a tool when the area in question is risky and/or hard to test.  Additionally, sometimes I need a GUI to provide simple functionality to test that I can’t do easily on my own.

For example, I’ve had 2 applciations were we implemented client side caching via Local SharedObjects.  Have you ever tried to delete these things?  Pain the ass, and slow.  What if you could just click a button IN your app?  That’s right, 3 clicks and they are dead?  What if you could see ALL SO’s you’re application uses, how much room they take up, and what their contents are… IN your application?  What if you could edit them?  Exacatly.  Flash Player allows you to delete them, but it’s tedious, requires an external website, and there is no good, x-platform apps that quickly give you business insight into your local cache.  When I say “business” I mean, relevant to your application.

For example, just because a Local SO has a ByteArray of BitmapData (since BitmapData doesn’t serialize properly) doesn’t mean it’s actually an image your GUI should show.  Perhaps you’re utilizing BitmapData as a faster multi-dimensional array, and saving them to the disk this way.  You’re GUI knows what to display, and how.

Another reason is ease of use.  Having PM’s and QA testing sessions in a browser based app is pretty straightforward in Safari and Firefox.  Same with new GUI changes; just clear your cache.  But what about Flash cookies?  “Right Click, choose ‘Cache Viewer’, hit the ‘Delete’ button”.  Hell, those instructions will fit in a Tweet!

The most infamous: “What version of Flash Player are you running?”

“How do I know?”

“Right click, and it’ll say.”

Booya.  Tools don’t have to be complicated windows… they could just be simple log messages that can be triggered, or information inside your right click menu.

Landmines

The last thing to touch on is land mines.  Logging, reporting, and diagnostic tools prepare you for the worst.  The worst is when you start removing land mines.  Sometimes you don’t know you have land-mines until someone steps on one.  Examples include the login service timing out.  The ENTIRE APP fails to work merely because of a hiccup in the server.  The client wasn’t written to… oh I don’t know, try again a couple of times.  Once it happens, you need to remove it.  Hopefully you’ll have a log message… like the login service never reporting an error, NOR a success.  If you don’t, you’ll learn your lesson, and log that shiz.  It’ll never get by you again.

…oh crap, a timeout.  No seriously, THIS TIME it won’t get by me again.  I’ll log when the timeout occurs AND whether or not they worked.

Now you’re talking.

Other more common land-mines include code that blatantly assumes no throws will ever be thrown.  Things like Loader.load, NetConnection.connect, or no try/catch blocks around navigateToURL.  Those things are just WAITING to explode.  If you don’t have a try/catch, they’ll blow up eventually.  If you do, but no log, this is MUCH MUCH worse.  It’ll explode, and no one will know.  Like when the tree falls in the woods, but no one is there to hear it, it doesn’t make a sound.  You need to log all errors.

…except for NetStream.close()… he’s the exception to the rule.

Bigger land mines include sections of code that break, and don’t tell anyone.  A lot of time developers won’t get a list of error messages, nor a GUI element to utilize in those cases.  Feeling insecure, they’ll either just log it, or perhaps LET it break on purpose to get someone motivated to provide design/UX direction.  It’s better to log those messages with proactive verbiage, and even using built-in alert controls (like Flex’) until a designer/management can provide the developer with what they need.  Informing the user of a problem with an ugly dialogue, and a log for QA testers/PM, is MUCH better than a hidden log message with no visual indication of what went wrong.

It may not seem like a land-mine, but if no one knows why clicking a button didn’t work, they’ll feel insecure about using the app.  If they are a stakeholder, this insecurity can lead to a fire drill.  Even if you and/or your team knows the problem, they don’t since you didn’t tell them.

Again, most land-mines from a consulting perspective are the ones you don’t know about.  A lot of times, the code base is too large for you to properly dig in and ascertain potential problems.  At least providing diagnostic tools for that region, or empowering others on your team to use/build them, keeps you abreast of what’s going on.  I’m not talking about null pointers; I’m talking about dependencies that you don’t know about breaking, and no one, including you, immediately knowing what’s wrong.

Using my JXLLogger v2

I’ve provided a sample logger I use in Flex & AIR apps.  You can use it in pure AS3 projects if you just utilize a simple LocalConnection.  It doesn’t follow all of my rules above, but it’s good enough to get the job done.  Simple drop the SWC into your libs folder, and go:

import mx.managers.PopUpManager;

PopUpManager.createPopUp(this, DebugMax, false);
DebugMax.log("Application::init, DebugMax ready and able, SIR!");

Thenceforth, anywhere in your application, you can go, DebugMax.log(), or debug, etc.

Cons

Having your application clearly talk to you and your team, with associated diagnostic & reporting tools to help augment your existing debugging capabilities… what could wrong that?

It’s more code.

More code means more things that can possibly go wrong.  More code means more things to maintain, to steal your focus from my core objective.  It’s even worse in Agile/Scrum where while it may be a necessity, to create code to help debug other code, yet you’re technically only getting the user story points for one particular feature.  While you get better at recognizing what tools you need to create, and thus factor that into your perception of the challenge associated with specific user stories, it’s sometimes hard to justify.

“Did you finish the login service?”

“No.”

“Why not?”

“…well, my server-reporting app that allows me to see if the server is awake took longer than anticipated.”

“You were only supposed to code 1 class that logged into the server, not right a server monitoring application.”

“Dude, that server goes down ALL the time and the LoginService class has no GUI; we don’t have an easy way to debug yet what errors are real, what are our code, and what’s that bloody server.”

“I don’t care, you’re clearly off task.”

“And you clearly are a douche!!!!”

See what I mean?  If you use the same arguments against Test Driven Development, they have the same negative consequences here, specifically, you’ve created more code to maintain.  Worse, that code isn’t often factored into project planning & budget.  It’s just assumed that if your design or data model changes, that you go update your tests classes because they “pay for themselves” in the future.  Hopefully that future is before your next UAT/deadline, and they + the things you need to get done that the client/your boss actually cares about are finished.

It’s really hard to argue against good logging.  Everyone benefits, and you can do it whilst you code.  Creating diagnostic tools can sometimes be justified as simple prototypes for a larger GUI.  If you have to create a real-time graph for example, that is REALLY complicated.  Creating a simple tool that just shows the values as they are is much easier, and VERY valuable in the long run to visually compare against your in-development graphing component.

Full blown diagnostic tools, however, can usually only be justified to those who’ve been doing this for awhile, are confident in your ability to not go off on a tangent (assuming you don’t have better things to do), and/or actually have a business need.

For example, Flex & Flash applications are SWF’s.  As such, they are a binary format that is self contained on the page, and doesn’t have massive integration with the browser like HTML/JS/CSS does.  Thus, common debugging and reporting tools & plugins available on the web do not work well with Flex/Flash apps as they do with HTML ones (ie Firebug, and various web developer toolbars built into some browsers).  Therefore, sometimes clients will specifically request monitoring tools and/or ways of testing the health of the application and/or getting reporting metrics from it.

Again, most of the times where these tools & techniques are valuable is when you’re consulting on a large code base you don’t know.  Like wrapping strange code with unit tests, they are created to give insight into how the code behaves since if it were good, it’d be easy to find out, and you wouldn’t need custom diagnostic tools.  You’re creating these tools for yourself to compare the information your good, working code is giving you about the “great unknown”. The more solid information you have in chaotic situations, the better.  You can be the calm in the middle of the storm, and slowly spread that calm over time.

In those situations, while management/stakeholders still want fixed features and new functionality, you’re clearly there as a consultant for a reason.  Establishing a strong beachhead that can confidently stand on to effectively assess the situation is the right thing to do.

Conclusions

A simple test to ascertain if you need to utilize logging & diagnostic tools in your application is to ask yourself: Does my current team have fire drills and our crises?  If yes, then yes, you need logging & diagnostic tools.

A simple test to ascertain if your application has land-mines can either be solved by doing a little digging yourself.  Do you commonly see sections of the code where obvious try/catch are needed?  Does the code assume a lot of things will never be null, yet have no centralized factory functions to ensure they aren’t?  Do things blow up in the app randomly, and know one on the team has a good idea as to why?

Using logging to make your application talk will help you develop and debug with confidence.  It’ll also have the wonderful side effect of having your team members, even the non-developers, getting insight into the application, sometimes solving their own problems, and providing you with helpful information to solve errors when they occur.  Nothing like having a verbose log with a JIRA ticket.

Using reporting tools can empower others to get finer grained information about problem areas, and having optional tools to corroborate problems, especially with 3rd party libraries & services.

Removing land-mines from the code ensures they won’t blow up; and if the do, you know, or knew, it was going to happen via a log message and/or diagnostic tool.  The real challenge is figuring out what land-mines you focus on, and those you don’t.  That just comes from experience.

Preventing stressful situations and empowering the team to have insight into the workings of the application goes a long way to earning trust with your client.  The app may be full of hundreds of little time bombs, but eventually you’ll know about all of ’em, and those you don’t, you’ll know why.  As will your team.  That allows you to kick ass… even if the current code base doesn’t.