“I’m fine re-architecting our various software applications used internally using Backbone/Angular for the front-end. However, why would I use Node for the back-end when my Spring MVC SOAP Java business layer works just fine?”

First, Backend for Frontend

It’s hard for Java Developers to get “why” if they are the same ones doing the front-end an the API for it. People like me (who are rare) and grew up on the front-end love this stuff. Case in point Sam Newman’s lovely “Backend for Frontend” article which summarizes a few of our challenges that Node (or Ruby… or Python… just easier with Node) solves.

Given a variety of devices, OR just different designs need different data, it’s easier to tweak in the back-end once, and have the client get it vs. munging things around all over the place on the client.

Second, Language Reuse

It’s easier for the team if they already know JavaScript to code the same language in both places vs. “Here, use Sublime for here, but Eclipse + JDK 7 for there… and Gulp + Node for here, but Maven for there… Gulpfile.js for here, but pom.xml & friends all over there…”. Same goes for the libraries & API; most are the same.

You get into this weird zone when talking about TypeScript. Many a Java dev has been fine with Java on the back, Flex/ActionScript 3 on the front. Years later, Java on the back, TypeScript + Angular on the front. That’s also ok… but again, the languages are still different. A good Java dev or team can leverage the strengths of both.

If you have a “JavaScript Developer” open role however, you can now put into a:

• front end role
• backend role
• devops role (manage Gulp/Docker/Jenkins)
• testing role (use Selenium)
• fullstack role via the MEAN stack or its ilk

That’s insanely flexible, price conscious for on/near/off shore, and staff scalable hence why language reuse is a huge deal because of the tools + roles that surround it.

Third, Scalability in Node is easier for Some Use Cases

… sort of. If you’re doing String parsing, Node does that well. However, for enterprise applications, no one argues the JVM is the shiz, hence Scala & Clojure. The point here, though, is most front-ends nowadays send JSON back and forth and munge it. All the work around that is just easier in Node. Parsing XML, JSON, etc. That’s what most REST API’s do.

The low-level work like Database access, security around SQL/NoSQL injection, etc. is all Java’s and the JVM realm for a lot of Enterprise clients. That’s why a lot of time you have people like me building my own REST API’s for my Angular application hitting Java back-ends. It’s just the norm most of our LLP clients have, many are legacy, a lot new, but both are heavily vested in Java. That’s fine, but it takes me 5 seconds to write an Express GET url to give me exactly what I need vs. begging some Java dev team already overwhelmed to get a node name changed that takes 2 weeks to deploy to QA.

Heck with that mess, orchestration layers for the win.

Finally, although not Erlang, Node’s awesome at Web Sockets. Given our ability to only use 1 core, we can write async code VERY easy (much like C# and Scala). Unlike them, ours doesn’t do parallel processing, but rather, tends to never “lock” the CPU since it’s just a pointer on the stack… unless you do gigantor for loops without using generator functions. Once you start forking processes, it makes it easier for non-longterm server guys (read Jesse Warden with the Associates in Art Degree) to scale back-end systems to the enterprise levels. Things like Redis make it uber easy to expedite fast REST API’s even when the legacy backend is slow. It also has pubsub to allow the cores to talk to each other behind load balancers.

… and again, sockets are just string parsing. Nowadays, you want to real-time data changes vs. stale front-end data (i.e. Meteor), and Node is often the one handling the sockets where Java handles the heavy REST data lifting.

I don’t know multithreading. I know how to easily scale Node to multiple cores with a simple pubsub using Redis to communicate and do basic clustering. That’s huge compared to what you need to know in multithreading to pull that off.

Fourth, Efficient Data

SOAP is garbage. It’s bloated, no one uses the strong typing on the client, and contracts are never enforceable, especially nowadays with microservices. JSON won the war. Flash & Flex developers knew that a decade ago.

Fifth, Spring vs. Spring Boot

Yes, Spring is old and not based on industry trends. Don’t re-write it, just update it. If you ain’t going full-reactive nor Scala/Go/Node, etc, heck yeah, Spring Boot FTW.

Sixth, Microservices

Some things Erlang does well. Some things Scala does well. Node & Java the same. With containers taking over the world, “if it ain’t broke, don’t fix it”. Some people don’t really care and choose a language/platform for other reasons years ago. That doesn’t mean you shouldn’t containerize it. If your back-end does in fact work, you have talent there to work on it, then just allow stuff that grows around it to just add to the microservice ecosystem you have. If another team wants to use [Node or New Framework], fine, have their microservice call your Java microservice. Hotness. Scalable.

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.

The following covers why you would utilize the Robotlegs MVC architecture in a lightweight, Lua game for Corona. I’ll discuss the refactoring reasoning, the common problems you run across in game architecture, and their solutions with their pro’s and con’s discussed. Finally, I conclude on how Robotlegs helps solve these common issues, specifically in a Lua & Corona context.

I’ve started the port of Robotlegs to Lua to work in Corona if you’re interested in learning more.

Refactor First

In learning Lua & Corona, I quickly ran into 2 problems with the game I’m working on. The main code controller became way too large to manage. It wasn’t quite a God object (yes, the anti-pattern) because a lot of the View’s themselves handled some of the necessary messaging & logic. Regardless, time to refactor.

The first thing was to start using classes. Lua doesn’t have classes. There are a bunch of resources out there that explain how to do them in various incarnations. I went with a version that Darren Osadchuk, creator of the Corona bundle for TextMate.

The second thing was to start using packages. Lua doesn’t have packages. There are various ways of implementing them which are all confusing as hell. The easiest way is to just put your code in a folder and use that path in the require function, but you can’t utilize folders for Android in the latest build of Corona at the time of this writing.

These are the low hanging fruit of re-factoring, and has made a huge difference in code readability & maintainability.

Burdens of Encapsulation

The downside of OOP is that it’s encapsulated. While making something a black box with internally managed state & implied reusability is good on the surface, it pushes the burden of managing communication between those encapsulated objects to someone ones.

You have 3 options: globals, messaging dependencies, or mediation.

Global Variables: The Good

Most people agree global variables are bad… in larger software development. In smaller scoped software gaming, not so much. Let’s explore their benefits.

In a lot of languages, globals are part of the language design, irrespective of how the runtime and tools/IDE’s handle them. Some languages make them first class citizens with mechanisms and rules around how they’re often used. This makes them formalized, accepted, AND useful. This is important to understand.

If it’s formalized, it means the language designers deem their usage acceptable, AND expected.

If it’s accepted, it means others will use them, incorporate them into their projects, libraries, and training & writing materials. This also means it’s then promoted amongst the community, solutions and coding strategies/solutions are built around it. This doesn’t make it inherently “good”, just accepted in that particular community.

If it’s useful, the majority of people will use it if their job is using that language as opposed to hobbyists, or those who continue to explore the language and try different ways to solve similar problems with it off of their employer’s clock.

In Lua, globals are all 3. Formalized via _G, very similar to ActionScript 1’s _global, accepted in that people do in fact use them (unknowingly a lot I’d wager), and useful since the syntax to utilize globals is terse; a Lua hallmark. Notice both have the preceding underscore to ensure they don’t interfere with the developer’s potential to create a variable called G or global. While ActionScript 1 has some security implementations to prevent certain loaded SWF’s from writing/modifying existing definitions, they had the same mechinism with strorage, first via _level’s on a per SWF basis, and later a formalized _global. Lua takes it a step farther with a series of facilities to change “which” globals your using, etc. It’s also used in package naming strategies, OOP, etc.

As a globally accessible table, access to _G is fast. Fast is good in game development. You want to be part of the solution, not part of the problem.

Global Variables: The Bad

This differs from traditional software development. If you come from any formal software development, globals are considered extremely bad practice. There is a common strategy to use the Singleton design pattern to “get away with it”. Even those are considered bad practice when over used. In fact, Singletons are often created merely because the language doesn’t offer a formalized way of doing global variables (like ActionScript 3 vs. ActionScript 1).

Why? The 3 main reasons are application state coupling, access control, and preventing testability.

Application State Coupling

Application State Coupling refers to the state of your application being dependent on usually a series of global variables. I won’t get into the why’s, but MVC and it’s MVP derivatives (Passive View, Supervising Controller, Presentation Model) have solved most of the state problems. They keep visual state in the View’s (or anything that’s a GUI that you can see), and application logic & state in the Model layer somewhere. Your application is no longer coupled to a single variable being a specific value for your application to run, to exhibit a certain bug, etc. Each piece can (usually, hehe) be run independently, and if there is a problem, you know where to look, or at least where NOT to look.

An example is if your player is dying too quickly, you know the problem isn’t in the player code, or the controller code, but rather somewhere in the model where his life state is being access/set/updated. If you used a global, it’d probably be set in player itself, or perhaps by an enemy bullet that hit him, etc. No clue where to look.

Another side effect is adding new global variables. This leads to certain parts of your application expecting the globals to be a certain value at certain times. If they aren’t, things don’t work. Because they are many different places, it becomes extremely time consuming for you to debug and track down because you don’t necessarily know who is expecting what to be set to what, and why. This is more caused by access control, however…

Access Control

Access Control refers to who can access your data, and how. In Flash & Flex apps that are smaller, we’ll usually use the server as access control. Meaning, while we provide a GUI to allow people to create, edit, and delete users from a database for example, the actual PHP/Ruby/Python/Java on the server is the access control. No matter what we do in the Flex/Flash, we can be assured the server (usually… *sigh*) will ensure we don’t delete people we’re not allowed to, delete users en-masse, put illegal characters into their name, etc. Basically anything that would corrupt the data and screw the up the GUI.

In Flex/Flash apps, and nowadays in larger JavaScript web applications, you have a notion of “application logic” or “application state”. This is because this state is no longer on the server. It used to be with some web applications, usually in the session. When you go add something to your cart on Amazon.com, it’s not stored on the page that much beyond to show you a slight graphical change. Once you change pages, that JavaScript & HTML page state is now gone and replaced with a new one… but it remembers what you added. It does this because the state is saved on the server since the client needs to be stateless if the user refreshes the page to go to another one.

We don’t have that problem as much in Flash/Flex apps. We don’t go to pages insomuch as new “Views”. These views, or graphical representations of a GUI that have internal state, are still in the same SWF embedded in the same page in a browser that doesn’t go anywhere (same thing for an AIR app on the desktop or on a mobile device). Therefore, someone has to be responsible for holding the data in a variable or series of variables, and updating it when the server gives you new data.

These are usually classes called “Models”, and they’ll usually mirror their server-side equivalents in terms of CRUD operations: create, read, update, and delete. Where they differ is how much of the server-side provided data is parsed, error handling, data access control, and how that server-side data is set internally.

Suffice to say, good Model classes are encapsulated, ensure application logic is accessed by a public API that ensures security, doesn’t allow the internal data to be corrupted, and does all this within reason. An example is our Player’s health. If every enemy collision and bullet out there has access to the player’s health, we have no easy way to track down who may be potentially doing the math wrong on calculating the new hit-points and setting them to invalid values, or thinking the player is dead when she’s not, etc. If you have a PlayerModel, you can ensure your problem’s regarding hit-points and letting the world know about player death is in one place, and problems with said state (how much health does the player currently have) starts in that class and those who access him. Access control in this case refers to ensuring the PlayerModel only exposes methods to increment/decrement the Player’s hit-points vs. allowing them to be set to -16, or NaN/Nil, etc. You don’t even have to worry about this; you just don’t allow it to happen.

Thus, the burden on accessing and setting hit-points correctly is pushed to someone else; those who access PlayerModel. THIS is where you look for bugs, but again, you need to ensure only a set few have access to the data access layer (PlayerModel).

In short, Models centralize data access, ensure it’s correct, testable, and DRY and prevent incorrect access errors, (i.e. global.playerHitPoints = “dude, pimp!”).

Preventing Testability

This third problem isn’t necessarily around unit-testing and TDD (Test Driven Development), but more around just ripping the class out, putting in a simple main.lua, and seeing if it works. If it has dependencies, they get dragged with it… and you have to instantiate and setup those guys. Suddenly quickly confirming some class or method works or not becomes a time consuming process that’s painful. If you can’t test something in isolation, you’ll have huge problems down the road isolating problems in a timely fashion.

Globals by their very nature are’t testable because they’re variables, not encapsulated classes. While Lua has some neat mechanisms to encapsulate globals in certain contexts, somewhere, someone is setting a global to some value in their own way. If a class depends on this global, that global must be set the same way before you test the class that relies on the global. Since you may not know who set the global a certain way, that global may not be the same in your test environment vs. in the game proper.

Global Conclusions

While globals in Lua are fast, formalized, and accepted, you must be aware of the rules so you can break them with confidence. First, keep in mind if you want to get something done, premature optimization is the root of all evil. With that in mind, ask yourself the quick question: Does creating a data access control class/layer around your globals to ensure it’s DRY and secure add so much overhead that the speed makes your game un-playable?

I’ve found this not to be the case in my implementations in Lua and ActionScript. They run fine, are encapsulated, and succeed in good access control. Thus, while globals are accepted in Lua, implementing a good coding practice via a data access layer does not adversely affect my performance while increasing my productivity in DRY’er code that’s easier to test with good encapsulation.

Messaging Dependencies

We’ve seen how globals can work to allow multiple View’s to talk to each other directly or indirectly via variables they all reference, or even methods/tables. We’ve also see how this leads to bad things like harder to find bugs and spaghetti code (you change 1 thing that adversely affects something else seemingly unrelated) as well as making refactoring more challenging than it needs to be.

One way to allow encapsulated objects to communicate is through messaging systems, also know as notifications or events (we’ll just call them events because that’s what ActionScript and Corona use). When something happens inside the object, such as a user clicking something, or some internal property changes, it’ll emit an event. There are 3 types of events we’re concerned with: local, global, and event context.

A local event is an event issued from an object/table. In ActionScript, anything that extends EventDispatcher, including DisplayObjects (things you can see), can emit events. In Lua, only DisplayObjects can; you have to build your own for regular tables as Lua doesn’t have an event system. So, if I create a wrapper table in Lua, I can then register for events from that table, and later when it emits them, I’ll hear them. Those are local events; events dispatched from an object/table directly. Although event objects/tables have the target property on them so I know where they come from, USUALLY event responders are not that encapsulated, and make the assumption that the event is coming from a specific object/table.

A global event is one that’s received, but we have no clue where it came from. At this point, we’re inspecting the event object itself to find context. If it’s a collision, then who collided with who? If it’s a touch event, then what was touched, and how? Global messaging systems are used for higher-level events and concerns. While you usually won’t have global events for touches because your mainly concerned with handling the touch event locally, a pause event for example could of been issued from anywhere, and while you don’t care who issued it, you’re more than capable of handling it (stopping your game loop, pausing your player’s movement, etc).

To properly handle an event, we need context. Context is basically the data the event, or message, has stored internally so when the handler gets it, he knows how to handle it. If the event is a touch event, cool, start moving. If it’s a touch release event, cool, stop moving. If it’s a collision, is it a bullet? If so, take less damage than say a missile hitting. Is the bullet’s velocity higher? If so, take more damage than usual. This context is what allows the encapsulation to happen. You issue a message, provide context, and whoever gets it doesn’t necessarily HAVE to know where it came from; they’ll have enough information to know how to handle it.

For Corona DisplayObjects, this is easy. You just use dispatch an event. But for Model/data access objects, not so much. You don’t want the overhead of a DisplayObject to just to send messages, so you build your own. This implies another class/table with the capability of sending/receiving messages. This means your classes will have a dependency on this object. For example, if I want to test my Model class in a brand new main.lua, it’ll bring along/require the messaging class. This is a dependency. One of the threads (just like OOP, encapsulation, keeping things DRY, don’t optimize too early, etc) you want to keep in the back of your head is to keep the dependencies low. You don’t want a class to have too many dependencies. Like globals, dependencies can cause spaghetti code, hard to test & debug situations, and overall just hard to manage code.

Corona makes the event dispatching dependency invisible with DisplayObjects because it’s built in. Not so for regular tables. Somehow, you have to put this dependency in every class. You can either create a public setter for it, and pass in an instance, or just reference a class globally in a base class. Both are a dependency, the latter just requires a lot less work and code.

Downside? It’s a dependency. You also force this implementation on everyone who wishes to utilize your class. If you make the messaging system events, 2 things happen. First, people using Corona get it because it’s the exact same API and functionality (excluding bubbling) that developers are used to. Secondly, it’s interchangeable and works with Corona DisplayObjects. The best solution would be to do Dependency Injection/Inversion of Control… but I haven’t figured out how to do this in Lua yet, and I’m not sure Lua supports metadata annotations. Considering it’s dynamic, you CAN inject things like this at runtime, but someone, somewhere has to do so. Why do so when every object requiring messaging needs the same mechanism? Thus, the pragmatic thing is to build it in.

Also, more importantly, DOES this messaging system add more performance overhead than using simple globals? To make the question harder to answer, can you make tighter coupling of your code and still get things done?

It’s been my experience, if you make things easier to use with less coupling, you’re more productive in the last 10% of your project. While coupling makes things easy in the beginning, it’s a farce; it has more than an exponential cost at the end.

Besides, you can always increase coupling easily; it’s removing coupling later that’s hard. If you need to optimize, great, you can. If not, great, no more work to do; you can instead focus on features. Usually, though, you’ll know pretty quick if you do iterative builds if a messaging system is making a huge performance impact on your game on not. The only surprises you’ll get is you spend days on something without a build. Do a small test, see if there is a noticeable difference. Sometimes you’ll have n-problems you won’t find till your game gets to a specific size which are unfortunate. An example is a charting component that works great building up to 5000 data points, but suddenly DRASTICALLY slows down beyond that.

These problems aren’t the fault of the API. If you take a step back, the “30,000ft view”, usually it’s the implementation that’s at fault, not the code itself.

For example, a little history lesson. Back when ActionScript 1 development was increasing in scope, we went through 4 different messaging systems. The first was the built-in one for Mouse and Keyboard, etc. It was only partially available; there wasn’t a MovieClip one. So, we used ASBroadcaster; an undocumented one inside of Flash Player. It had a known bug with removing a listener during a dispatch, and other things. Then Bokel released a version on top of that fixed it. Then Adobe created EventDispatcher, mirroring the ECMA one. They then built this into the Flash Player for Flash Player 9’s new virtual machine.

There were others that came out after ActionScript 3 was born. PureMVC had notifications in it for an easier port to other platforms & languages. Robert Penner created Signals for a light-weight, object poolable, quick to develop in C#-esque messaging system.

As you can see, why the bottleneck for most larger Flash & Flex 1.x applications at the time was EventDispatcher, even when they built it into the runtime in C, developers opt-ed for a slower system built by themselves to solve different problems.

So why the continuous talk about performance questions in this section when I rail against premature optimization? Because messaging is the core of any app, or game. The choice you make is the largest impact on what you’re building, both from performance and from a development perspective. Yes, you can just use direct access to objects, or callbacks, but that’s not very encapsulated, nor DRY, and is a pain to re-factor later if you need. Messages via Events are more encapsulated, and less coupled, but have a performance impact. Additionally, only DisplayObjects use the internal C implementation; your own uses interpreted Lua with whatever JIT’ing/machine/voodoo conversion Corona does.

Traditionally, it’s easy to switch to events from callbacks, but not the other way around. While the performance impact isn’t that large to utilize a DisplayObject and use the built-in event messaging, based on some benchmarks, this isn’t a good idea to build upon.

Mediation

The third option is using the Mediator pattern. Once you have 2 encapsulated objects that need to talk to each other, you utilize a class that handles the communication. It takes the message from ViewA and sends that to ViewB. When ViewB wishes to talk to ViewA, it sends the message and the Mediator relays it.

All the MVC/MVP articles go over A LOT about the different things a View should/should not do, particularly with it’s needs for data and how to show it. Regardless of the implementation, it’s generally understood that someone such as a Mediator or a Presenter handels the responses from a View. If it’s a Presenter, it’s a dependency in the View, and the View calls methods on it. This allows the actual logic behind both responding to View user gestures (like when I touch a button on the phone) to not muddy up the View (muddy up means TONS of code that has nothing to do with displaying graphics, putting into groups, setting up Sprite Sheets, etc), and allows you to test the behavior in isolation.

Mediator’s are similar, although, the View has no idea he/she has a Mediator, and the Mediator has the View reference passed into it by someone else. Again, more encapsulation, yet SOMEONE has to have the burden of setting up this relationship. In ActionScript this is easy; Robotlegs just listens for the Event.ADDED_TO_STAGE/REMOVED_FROM_STAGE events and creates/destroys based on an internal hash/table. In Lua, you don’t have any DisplayObjects events, so you have to manually do it.

Either way, if you DON’T Mediate your View’s, you’ll eventually have a lot of code in there that has to “know” about other objects. This’ll be either a global reference, or a dependency… and we’ve already talked about why those things are bad to do. Additionally, tons of code in general is bad; having a View just focus on graphical things and emitting events people outside would care about while the logic can be put elsewhere makes it easier to manage. When you open a View class; you know pretty quickly what you’re looking at is just GUI specific code.

There’s another more important aspect of Mediation that is similar to messaging and that is system events that affect Application Logic.

For example, many things in a game care about a Player’s health.

• the Sprite that represents the player; it needs to show different graphics for how much health it has
• a health bar at the top right of the screen that fills up with green the more health the player has
• sounds that play when the player loses and gains health

If you use globals, you’d have all 3 handled by the actual Player sprite class. It’d update it’s internal health and update the global variables. Those who have references to the globals would be informed when that value changes. Additionally, you’ve now wired them together if you do this. If you change one, you’ll break the other.

Using a Mediator allows:

• the player and the health bar both the capability to react to the change in the hit points in an encapsulated way. If you change how the Player and HealthBar look/work, the actual logic on how yo do that is centralized to either them, or their Mediators… and usually Mediators are like 1 line of actual code to change.
• The application logic of how hit points are updated and changed to be done in 1 place. As your game grows and different enemies need to do different types of damage to your player, and sometimes react differently depending on how much health the player has, this is all done and updated in 1 place. It’s DRY, and easy to find where the logic bugs are.
• A side effect of this is… the Mediator pattern (lolz). You can have View’s the capability of talking to each other without having tight coupling.

The most important feature is solving the classic race condition of is the data ready for a View when he’s created, or is it null and he has to wait. Using Medaitors, you don’t have this problem. In the onRegister, you just set it if you have it on whatever Model(s) you need, else just wait for the Model(s) to be updated and inform the view.

…I wouldn’t say totally solved; handling “null” or “nil” is still a challenge for developers even in simple View’s. Those are good problems to have, though vs. race conditions.

If you enter the optimization phase of your game and want to remove events, use callbacks, and have hard-wired references, that’s fine if benchmarks truly identify that you need the performance gains. Usually, though, Mediator communication isn’t your bottle neck, it’s collisions, lack of object-pooling, and how messages are handled.

Quickie on Commands

Commands are just formalized Controller logic. In fact, in other frameworks, they’re simply Controller classes with methods. They’re called “Commands” because they do 1 thing… and can potentially undo it. If you’ve ever used an Adobe Product, a few of them like Dreamweaver, Fireworks, Flash, and Photoshop will have a Command list, also called “History Panel”. In Flash and Fireworks, you can even get the code for these Commands. The line blurs here once you lump them all together, but in my experience, good Controllers have 2 things in common:

1. They contain the only code in the application that updates the Models (update/delete in CRUD for internal data)
2. They contain all application logic… or at least share the burden with the Models.

For #1, this is important in tracking down bugs and keeping your code DRY. You always know who’s changing your Player’s hit points, who’s actually applying your level up rewards, etc. If you can test your Models in isolation, and they’re good… then you know who to blame. This is good because again, they tend to often start by being 1 line functions with the potential to grow to 30 to 60… not a bad way to start life, nor grow. Small, readable code.

For #2, whether you have a Controller class function, or a Command, SOMEONE in your application needs to “load the level data” from your level editor. SOMEONE needs to handle the fact that your player just drank a health potion, but he’s also wearing a Ring of Health Boost + 2, and this positively affects the effects of the health potions she drinks. SOMEONE needs to handle calling the loadSaveGame service, ensuring it worked, and updating all the Models with their relevant Memento data.

This orchestrator of pulling everyone together, to read multiple Models and “make decisions”, they’re the brains of your application. For performance reasons, a lot of Controller logic is often done directly in game views, even if it just references a Controller class for ensuring logic is somewhat DRY.

There’s a lot of loathing in the community by those with a more pragmatic bent, or just on smaller code bases with shorter deadlines. The overhead associated with them completely negates their perceived value when you can just call a centralized Controller logic function via… a function call vs. some event that magically spawns some other class that has 1 function with a bunch of injected dependencies. Just depends in you read that last sentence and go “Makes sense to me, don’t see what the issue with it is… ” or “w…t…f… why!?”.

Conclusions

Remember, the above is all complete bs. If you or your team have a way of building games that works for you, great. This is just helpful tool I’ve found in Flash & Flex application development, and it seems to help me in Corona games, specifically around the GUI/HUD portions. I still have globals in my collision routines for speed purposes, hehe.

Additionally, it’s a great teaching tool, too. Joel Hooks got some similar schlack like I did in using PureMVC when he was first starting out in Objective C for iPhone. Providing a comfortable & familiar framework of development really helped him learn and have context how the new language & platform work with certain concerns; it’s how he shipped his first app on the app store. Same with me in Corona… and game development.

Finally, this isn’t an all or nothing approach. You can just use it on the parts you need, or perhaps just to learn. I find its helped me learn a lot about Lua and Corona, as well as having the flexibly to change the API of my Player and Enemies without affecting how the GUI itself around the game works. In true spirit of total disclosure, I’ll report on any adverse overhead if I find it.

The following discusses how to utilize Dependency Injection in the Cairngorm 2.x framework, explains why you’d want to do this, and shows the code you need. Included is a brief explanation of how you Mock or “fake” a backend until it’s ready so you can build your Flex app without waiting for the web services to be ready.

NOTE: I do not professionally recommend you do the following integration outlined in this article. Instead, I suggest you utilize Robotlegs or Parsley at the start of any Flex application of large size. They, and other frameworks of their ilk (Swiz, PureMVC, etc), have solved many glaring architecture problems Cairngorm has over the past 7 years. There is a reason Cairngorm 3 is a bunch of good ideas, and not a framework. Adobe recommends you use Cairngorm 3 with one of the aforementioned frameworks.

Context

Your project uses Cairngorm 2.x. Your back-end services aren’t done yet. Your team has a lot of GUI code to write. Ya’ll cannot wait for the middle tier to be done to actually move forward. The way to solve this is to use Mocks; classes that fake your middle tier. They’ll take a few seconds to respond, use the same methods, dispatch the same events, and return real ValueObjects. This allows you to write real GUI and Application logic code without having to wait on your server to work. If you’re server works, and then it turns out to be premature (i.e. “That isn’t supposed to happen… worked for me…”), you can go back to your Mocks until it’s “really” ready.

Mocking a Middle Tier

The easiest way to do this strategy is via coding by contract and Dependency Injection. You code to interfaces instead of concrete implementations (you use ILoginService vs LoginService). Your injection rules then have a switch: “real” and “fake”. If real is turned on, you hit a real server. If fake is turned on instead, you don’t hit anything. Both take a few seconds (read, more than 1 frame), and both return real ValueObjects. The fake ones do this by hardcoding the return values to something that would commonly be returned.

Examples include faking a login. The MockLoginService will take a hardcoded username and password and return a hardcoded UserVO. The real LoginService will take any username and password, and return a UserVO if successfully logged in that the server gave it.

Both use the same API. Both dispatch the exact same Event(s). Both expose the same return values. The key is the both implement the same ILoginService interface. This allows your DI framework to create the service for you vs. using Boolean or Conditional Compilation flags everywhere.

Example Login Service

Here’s an example of a real Login Service, specifically a Cairngorm Business Delegate that is assumed to have a predefined remoting-config.xml that defines your BlazeDS/Java services, and you access via a ServicesLocator/Services Singleton.

package com.jxl.services
{
   import mx.rpc.IResponder;
   import mx.rpc.AsyncToken;
   import mx.rpc.Responder;
   import mx.rpc.events.FaultEvent;
   import mx.rpc.events.ResultEvent;
   import mx.rpc.remoting.Operation;
   import mx.rpc.remoting.RemoteObject;

   public class LoginService implements ILoginService
   {

      private var responder:IResponder;
      private var service:RemoteObject;

      public function LoginService(responder:IResponder):void
      {
         this.responder    = responder;
         this.service      = ServiceLocator.instance.getRemoteObject( "LoginService" );
      }

      public function login(username:String, password:String):void
      {
         var operation:Operation    = service.getOperation("login") as Operation;
         var responder:Responder    = new Responder(onResult, onFault);
         var token:AsyncToken       = operation.send(username, password);
         token.addResponder(responder);
      }

      private function onResult(event:ResultEvent):void
      {
         responder.result(event);
      }

      private function onFault(event:FaultEvent):void
      {
         responder.fault(event);
      }
   }
}

Notice it takes your username and password, passes to the predefined service, and awaits a response from the passed in Responder.

Now here’s the fake one:

package com.jxl.services.mocks
{

   import flash.utils.setTimeout;

   import mx.rpc.IResponder;
   import mx.rpc.Responder;
   import mx.rpc.events.ResultEvent;

   public class MockLoginService implements ILoginService
   {

      private var responder:IResponder;

      public function MockLoginService(responder:IResponder):void
      {
         this.responder = responder;
      }

      public function login(username:String, password:String):void
      {
         setTimeout(onResult, 2 * 1000);
      }

      private function onResult():void
      {
         var fakeUser:UserVO    = new UserVO();
         fakeUser.firstName     = "Jesse";
         fakeUser.lastName      = "Warden";
         responder.result(new ResultEvent(ResultEvent.RESULT, false, true, fakeUser));
      }
   }
}

It, too, implements the ILoginService, as well as dispatching the ResultEvent to the passed in Responder. Notice it creates a fake user, doesn’t care what you pass in, and uses a 2 second timer to emulate a server call. This seems trivial, but a lot of people coming to ActionScript for the first time from other blocking languages such as C++ or Java assume the server will respond in the same block/stack of code vs. waiting for an event. Using this timer helps surface such workflow issues early.

And the ILoginService interface both of the above implement:

package com.jxl.services
{
   public interface ILoginService
   {
      function login(username:String, password:String):void;
   }
}

Using Boolean Constants

Before Dependency Injection frameworks, you’d use Boolean config variables in some Constants file:

package
{
   public class Constants
   {
      public static const USE_MOCKS:Boolean = true;
   }
}

And then implemented in your Cairngorm Command like so:

package com.jxl.commands
{
   import com.jxl.services.LoginService;
   import com.jxl.services.mocks.MockLoginService;
   import com.jxl.services.ILoginService;
   import com.jxl.models.LoginModel;
   import com.jxl.events.controller.LoginEvent;

   import com.adobe.cairngorm.commands.Command;
   import com.adobe.cairngorm.control.CairngormEvent;

   import mx.rpc.Responder;

   public class LoginCommand implements Command
   {
      private var responder:Responder;
      private var delegate:ILoginService;

      public function execute(event:CairngormEvent):void
      {
         responder                 = new Responder(onLoginSuccess, onLoginError);
         var loginEvent:LoginEvent = event as LoginEvent;

         if(Constants.USE_MOCKS == false)
         {
            delegate               = new LoginService(responder);
         }
         else
         {
            delegate               = new MockLoginService(responder);
         }

         delegate.login(loginEvent.username, loginEvent.password);
      }

      private function onLoginSuccess(event:ResultEvent):void
      {
         LoginModel.instance.loggedInUser = event.result as UserVO;
      }

      private function onLoginError(event:FaultEvent):void
      {
         trace("LoginCommand::onLoginError");
      }
   }
}

There are 3 problems with the above approach.

1. It’s all or nothing. Once you set the Constants’ file USE_MOCKS variable to false, EVERYTHING is in production mode. A lot of times a critical service will go out of commission, or be updated. You don’t have the ability using the above to target specific Services/BusinessDelegates to be mocked, while the rest are still production.
2. QA will often request certain services fail intentionally while others succeed; using the above prevents you from giving QA that ability.
3. You have if/then’s everywhere. This can lead to code bloat, specifically in Commands that actually handle multiple events vs. single event types (see Point #6)… or Commands that handle the service call chaining themselves (similar to Robotlegs AsyncCommand’s that choose not to fork, but instead handle everything internally (+ rollback if needed).

Using Conditional Compilation

Same as the above, but uses constants defined by the compiler to determine whether to even compile in certain code. Wherever you configure mxmlc, it’d look something like this:

-define=SERVICES::usemocks,true

And then in your Cairngorm Command:

if(SERVICES::usemocks == false)
   delegate = new LoginService(responder);

if(SERVICES::usemocks == true)
   delegate = new MockLoginService(responder);

Just as ghetto; you still have C-like #ifdef’s everywhere. Gross. Manual. Prone to error. Still globally set on or off; all or nothing. Additionally, requires you to configure the compiler vs. “just code”. More crud to setup, maintain, and ensure goes into your automated build configuration.

Using Dependency Injection via SwiftSuspenders

NOTE: You don’t necessarily have to use SwiftSuspenders, or even Robotlegs. I’m just using them in this example because I know them.

Dependency Injection, also know as Inversion of Control, or IoC is a way to have your dependencies injected into your class for you. It’s the “new ‘new'”. Instead of you going:

delegate = new LoginService(responder);

This is done for you; you never write new Something again for your dependencies. Now generally, it’s fine to code to Concrete implementations. But hopefully, you can see how coding by contract (ie using ILoginService) above allows you to configure WHICH Login Service to use; the real one or the fake one.

This is where DI comes in. You configure that stuff in one place; globally, or on a case by case basis, usually using ActionScript. An example, this time using the same Constants variable and an already made SwiftSuspenders injector:

if(Constants.USE_MOCKS == false)
{
   injector.mapClass(ILoginService, LoginService);
}
else
{
   injector.mapClass(ILoginService, MockLoginService);
}

As you can see, this accomplishes a few things.

First, it makes your configuration rules DRY. Instead of having if/then’s or SERVICES::usemocks everywhere, you do it all in one place/class. Second, you can choose to turn it off for specific services. Third, anywhere you utilize ILoginService, this injection rule will run, allowing you to use the same rules in unit tests (although you shouldn’t, hehe), and any other place you’re coding by contract. It also keeps your code concise; it’s just coding to the interface; it has no clue what real type it actually is (LoginService or MockLoginService).

For our purposes, this is perfect for setting up and configuring mocks. We can configure our entire application to use real services once they come online… or just 1 at a time, all in one place.

DI in Cairngorm

Cairngorm has a prescribed way of writing your service layer (sort of… ok not really). Thus it’s implied you’ll be using BusinessDelegates to connect to your back end and get your data. Additionally, Cairngorm prescribes you utilize Commands to their interface to instantiate and utilize those Services/BusinessDelegates.

Cairngorm 2.x does not have a documented way of doing Dependency Injection. There is a SpringAS adapter for Cairngorm David Buhler told me about on Facebook, but I haven’t investigated it myself.

There are 3 challenges you need to be aware of:

1. Cairngorm is typically deployed as a SWC; a library. Thus, you don’t have access to the source to modify. You could, but this makes people nervous.
2. Cairngorm creates Commands internally in it’s FrontController.
3. BusinessDelegates utilize an IResponder for their constructors (by convention), which would require you to utilize constructor injection. While it’s supported, it’s confusing for people who haven’t done it before. Even so, mx.rpc.Responders in turn have a specific constructor only approach to creation. In short, it’s “just easier” to modify the convention of setting responders on BusinessDelegates after they are created via getter/setters vs. using Alan Shaw’s Factory injection rule modification… and even that doesn’t work at the instance level where it’s most often inside of Commands anyway. More on this in a bit.

So we can’t modify Cairngorm’s source code, we need to inject our dependencies manually into Cairngorm Commands, and we need to slightly modify the Cairngorm BusinessDelegate convention to use a public setter vs. a constructor parameter.

No problem. Here’s the 3 steps you need to follow.

Step 1: Setup Your Injection Rules

You need to setup your injection rules. Since I’m comfortable using SwiftSuspenders, and Robotlegs already does most of the hard work inside it’s Context class, I’ll just use that; I create a MainContext.as class that sets up my rules and instantiate it in my main Flex Application class.

Here’s the class (again, you’re welcome to use your own ActionScript DI library like Swiz/Parsely or any Guice/Spring derivatives):

package
{
   import com.jxl.events.controller.AppEvent

   import flash.display.DisplayObjectContainer;

   import org.robotlegs.mvcs.Context;

   [Event(name="applicationReady", type="com.jxl.events.controller.AppEvent")]
   public class MainContext extends Context
   {
      public function MainContext(contextView:DisplayObjectContainer=null, autoStartup:Boolean=true)
      {
         super(contextView, autoStartup);
      }

      public override function startup():void
      {
         if(Constants.USE_MOCKS == false)
         {
            injector.mapClass(ILoginService, LoginService);
         }
         else
         {
            injector.mapClass(ILoginService, MockLoginService);
         }
         var appEvent:AppEvent = new AppEvent(AppEvent.APP_READY);
         appEvent.injector     = injector;
         dispatchEvent(appEvent);
      }
   }
}

Step 2: Give Cairngorm Injection Powers

Most of the work in a Cairngorm application is done in Commands. This is where we’ll need to inject the majority of our dependencies. In Cairngorm, you extend its FrontController class to basically wire up CairngormEvents that are dispatched to run certain Commands. Internally, it’ll create & execute these command classes for you. We need to override this behavior so we can inject our dependencies before the Command’s execute method is called. This implies the class that extends FrontController even has an injector, which it doesn’t.

So how do we go about it?

1. Give your FrontController.as sub-class an injector public property.
2. give your FrontController an injector instance
3. override executeCommand to inject into the Command class

You’ll notice in Step 1 I dispatch an “AppEvent” and attach the MainContext’s injector property. This is because the Cairngorm FrontController needs it, and MainContext makes that a protected property. Putting it on an event class allows us to know when it’s ready to use, and to smuggle it out of the class so others can use it.

First, make your public property addition to your FrontController sub-class:

public var injector:Injector;

Second, set it. I do this in the Flex 4 Application class, like so:

<fx:Declarations>
   <jxl:MainContext contextView="{this}" applicationReady="onInjectionsReady(event)" />
   <cairngorm:MainController />
</fx:Declarations>

<fx:Script><![CDATA[
   private function onAppReady(event:AppReady):void
   {
      mainController.injector = event.injector;
   }
]]></fx:Script>

Third, override executeCommand in your FrontController sub-class. It looks like this:

protected function executeCommand( event : CairngormEvent ) : void
{
   var commandToInitialise : Class = getCommand( event.type );
   var commandToExecute : ICommand = new commandToInitialise();

   commandToExecute.execute( event );
}

Make it look like this:

protected override function executeCommand( event : CairngormEvent ) : void
{
   var commandToInitialise : Class = getCommand( event.type );
   var commandToExecute : ICommand = new commandToInitialise();
   injector.injectInto(commandToExecute);
   commandToExecute.execute( event );
}

Step 3: Implement Your Commands & BusinessDelegates

First, here’s our modified LoginCommand. Notice 3 things. First, the delegate is now a public variable that has the [Inject] tag on top; it must be public otherwise the [Inject] tag won’t work. Second, notice we don’t instantiate delegate; we just assume (rightly so) it’s already instantiated. Third, and most important; we’re setting the responder directly on the Delegate vs. putting it in the constructor like a lot of Cairngorm examples do.

Remember, whether we’re using Mocks or a real server, the Command will stay the exact same.

package com.jxl.commands
{
   import com.jxl.services.LoginService;
   import com.jxl.services.mocks.MockLoginService;
   import com.jxl.services.ILoginService;
   import com.jxl.models.LoginModel;
   import com.jxl.events.controller.LoginEvent;

    import com.adobe.cairngorm.commands.Command;
    import com.adobe.cairngorm.control.CairngormEvent;

    import mx.rpc.Responder;

    public class LoginCommand implements Command
    {
      [Inject]
      public var delegate:ILoginService;

      public function execute(event:CairngormEvent):void
        {
         var loginEvent:LoginEvent = event as LoginEvent;

         delegate.responder = new Responder(onLoginSuccess, onLoginError);
         delegate.login(loginEvent.username, loginEvent.password);
        }

      private function onLoginSuccess(event:ResultEvent):void
      {
         LoginModel.instance.loggedInUser = event.result as UserVO;
      }

      private function onLoginError(event:FaultEvent):void
      {
         trace("LoginCommand::onLoginError");
      }
    }
}

Second, just modify your BusinessDelegates on how they get IResponders. So, instead of this:

private var responder:IResponder;
private var service:RemoteObject;

public function LoginService(responder:IResponder):void
{
   this.responder = responder;
   this.service = ServiceLocator.instance.getRemoteObject( "LoginService" );
}

…do this:

public var responder:IResponder;
private var service:RemoteObject;

public function LoginService():void
{
   this.service = ServiceLocator.instance.getRemoteObject( "LoginService" );
}

Now, I’m one of those people who hates useless getter/setters to that don’t actually DO anything. That said, you can put getter/setters in interfaces to ensure your BusinessDelegates follow the contract. Up to you; find a convention you like.

…or just do constructor injection.

Conclusions

I’ve used Mocks on 3 projects now, 1 small, and 2 large and it has significantly improved my teams velocity in all 3 instances. Usually the person setting up the Mocks tends to be a bottleneck for a day or so, but once in place (and assuming you have some idea of the ValueObjects you need), your team can start moving immediately regardless of the state of your server.

This is helpful in Design Agency work where deadlines are non-negotiable, and the server team is just as stressed as you are. It’s useful in Enterprise situations especially where you might not have a working server + services + production-like testing environment for 5 Sprints. That’s at least 3 months with NO dependable services. I’ve seen it take way longer than that, as well.

Keep in mind too that if there are no injection rules defined, noting will happen. This is important if you’re converting an existing code base and want to help remove some of the dependencies from it. You can lay your DI framework on top, and Cairngorm wil still work the same. This is nice in that some Cairngorm code bases are some of the largest Flex code bases known to man (I guarantee you right now some Corvette driving Parsley proponent is claiming his is bigger).

Remember, you just: Setup your injection rules, give the FrontController an injector, and override executeCommand to use that injector to inject into the Command classes for their dependencies. The rest is convention.