Legacy Code Part 7: How To Map Your App

So, in our last post we talked about Mapping Your App being your next step, but then a question came to me, "How?"

Well, that's a very valid question. When I took on this exercise, several years ago, with one very large (6000+ template) application, I began by making a basic flow diagram of the existing Application.cfm and OnRequestEnd.cfm. What this ultimately did was A) show me all of the small bits of process flow occurring in these templates, and B) gave me a true understanding of exactly what was happening when. This all allowed me to evaluate each of these small bits of functionality, and determine how they each translated into the new ColdFusion application framework, as it is laid out by Application.cfc.

You can typically break your application down into a few sets of events: Application Start and End, Session Start and End, and Request Start and End. On top of this you have a few edge case events you can cover, like if a request is made of a template that doesn't exist (onMissingTemplate), or it an error is thrown but not caught otherwise (onError).

OK, so saying all of that kinda makes sense. But, what does it mean from an application standpoint? Well, then you have to evaluate the variables you're creating and make sure that you're placing them in the proper persistent scope. You have a utility object that you use everywhere in your application? Then you put it into the Application scope during onApplicationStart. Have a single user object that you use to model each user during their visit? Then you put it into the Session scope during onSessionStart. Want to track each page request by logging specifics to your db? Set some variables at the beginning (onRequestStart), or during your request, then execute your sql inserts when the request is done (onRequestEnd).

You'll start with your initial flow diagrams, and then create some new ones with headings to match the new application framework of Application.cfc. Create a diagram titled "onApplicationStart", and bring in the corresponding flow bits from your other diagram. Move flows around until they're in the order necessary, and in their proper place in event execution flow. Once you moved all of the small sub-flows from the old to one of the new, then you have a roadmap for writing your new Application.cfc.

Need cheap software for making basic flow diagrams? I use the draw.io app from the Google Chrome Web Store.

This article is the sixth in a series of articles on bringing life back to your legacy ColdFusion applications. Follow along in the Legacy Code category.

Legacy Code Part 6: Map Your App

You've picked up some new hardware, setup a new local dev environment, and started learning the ins and outs of the modern web age. Your Legacy Code is getting more out of touch every day that goes by. Now what?

Let's get started. The first thing you need to do? Map your App. One of the best things to happen to ColdFusion (many, many moons ago) was the introduction of Applications.cfc. Application.cfc replaces Application.cfm and OnRequestEnd.cfm, allowing you a much finer level of control of your application flow. Here's where a solid understanding of how your application works is most important, as you now have the ability to truly target the creation (and destruction) of variables in different persistent scopes.

Remember when I said it was time to learn the latest ColdFusion? Well, this isn't really "new", but it might be new to you, or to this app. A solid understanding of what happens at each stage of process is important, as well as truly understanding proper scoping. I've already blogged about the different stages of application flow in my MSOC series, and you can download my scripted Application.cfc as a template.

Understanding how and when certain variables are added to your application will help you to identify where things might be sloppy or slow. By making your own diagram, you can write out how your app begins, then a session, then an actual request, and then those ends again. You begin to ask yourself "Does this really belong in the Session scope? Or would it be better served in the Application scope?" If your app is on it's own on a system, you may even decide that there are things you could place in the Server scope, and begin to explore using a Server.cfc for onServerStart().

Diagramming your application flow can be very enlightening, and liberating. You really begin to see where some of your app's inefficiencies lie, and how you can regain control. With such fine grained control, it's much easier to write in "reinit" functionality for "resetting" your application. You find that audit logging is much simpler (or just possible) when attaching to every request at onRequestEnd(). You begin to realize that you're hanging on to some data for much longer than you need to, or that you're requesting data entirely too frequently when you really only need it occasionally.

After you've completely diagrammed your application flow, you might begin writing your Application.cfc. Keep in mind that some of your findings may take hours, days, or even months to correct. Yes, that variable really needs to be in the Application scope, but that also means you have to change every reference to that variable across your entire application. Now might not be the time to do that yet. Chances are you will begin with writing your Application.cfc as a direct replacement for your Application.cfm and OnRequestEnd.cfm, and then gradually, over time, correct your past errors. You've got it all diagrammed out now, and having it in writing will assist you in your future patchwork.

What you're doing here is beginning to make a plan. Over time you are going to systematically refactor small pieces of code across an entire application. Migration to Application.cfc is the first of many steps, and probably one of the largest, overall. It's also one of your most important steps, as it really gives you a blueprint for the future.

This article is the sixth in a series of articles on bringing life back to your legacy ColdFusion applications. Follow along in the Legacy Code category.