Solo Web Startup

Aaron Longnion
http://refynr.com

\s+(where|set)\s+[a-z_\.]+\s+(like|\=)\s+'?%?#[a-z"_'\.\(\)\+\/]+#%?'?

Aaron Longnion
http://refynr.com

To play catch-up, see the first 3 parts of this series:

http://aqlong.posterous.com/making-the-best-of-legacy-cf-code-part-1

http://aqlong.posterous.com/making-the-best-of-legacy-cf-code-part-2

http://aqlong.posterous.com/making-the-best-of-legacy-cf-code-part-3

As promised in Part 3, I will talk about security and automated testing in this post:

• Automated Testing:
  • Unit Testing: a while back there was CFUnit and CFCUnit, but the development of each is not current like MXUnit.org, which includes many features such as an Eclipse plugin, Method-level testing, Debug output, ANT tasks, and Test Stub generation. 

    But to decide if your team should use this, in my experience it depends on your company's tolerance for bugs and poor quality, if your developers know how to unit test, and if the leadership of your team is in favor of unit testing.

    Your company may be fine with spending about 5-10 business days after every major release fixing bugs and other issues that probably would've been caught with good unit & functional tests. If this is the case, you don't really have a chance in hell in implementing Unit Testing as part of your Development process. Your customers may also have experienced so many bugs with the system over the last 10 years that they come to expect it, so you're going to be hard-pressed to convince your boss to change if no one really has a problem with the "status quo". Or maybe you're a better salesman than me...? :D

    If no one on your team has experience or training with unit testing, I've also found that it is a very long uphill battle to get a team of even just a few developers to adopt unit testing. Yes, I've put together my own company presentations and trainings, and many developers just don't see how unit testing is going to make their lives easier - they just see it as extra work.

    If the Project Manager, Architect, and/or Lead Developer are in favor of Unit Testing, you may have a fighting chance. These leaders can make it a requirement that all CFC, functions, UDFs, and in some cases Custom Tags or include files *must* have Unit Tests to go with all code that is committed to source control. Once Unit Testing is a requirement, within a few weeks everyone will see the benefit, and it even become fun!

    Even if you can't get approval to make Unit Testing a requirement, go download MXUnit and try your hand at writing some simple Unit Tests. It's a great learning experience, and seeing dozens of tests that your wrote "pass" and turn green can be quite euphoric to nerds like us ;-)

  • Functional Testing: ideally, there should be at least one professional Quality Assurance (QA) Tester for your system, if not a small team. This should not be just one of your developers. Yes, each developer should thoroughly test all possible functionality (Use Cases) of new features and changes made to your code while programming, but it should not be their responsibility to say whether or not it is ready to go live to Production. 

    A QA specialists knows how to really test web applications properly. They will write all sorts of automated scripts with Selenium or Watir (or other), can promote your code from development to your Staging/Testing environment so that they can constantly test your latest code, and they should know a thing or two about stress/load testing your apps to make sure they will perform if your app gets a lot of traffic. Over time, they will learn how the legacy app works better than most developers because they must "Regression test", which means that they will do automated and manual tests of all the major parts of your system on a regular basis, and especially before major releases, to make sure that not only the new code works but that nothing broke inadvertently when you changed code or did a "merge" in your source control system.

    But if it's not possible/feasible to hire a QA Tester, then developers will usually be the ones doing the bulk of the testing. If you can get other employees and customers to help test, that's good, too, as long as you have an efficient way to manage all reported bugs. For developers testing their own application, the least you can do is make sure that developers aren't the only ones testing their own code. At least one other developer should test all possible functionality for another developers code. This kills two birds with one stone: 1) the 2nd developer learns the new functionality, and 2) the 1st developer probably didn't think of all possible Use Cases, so the 2nd developer will usually catch something unexpected. 

• Security: A lot has been written on this subject, so I'll just say that I'd start with cfqueryparam. You probably know this, but putting cfqueryparam around your variables in your SQL will secure your SQL against SQL Injection attacks, and has the added benefit of improving the performance of the queries. Here's a quite old article on it from Ben Forta himself. If you have hundreds or thousands of queries to fix, prioritize the public-facing ones (public web site, login pages, etc.) to do first, and then work on the rest as you have time. 

  How do you quickly find all the queries which should have cfqueryparam?  I have a RegEx that, while isn't perfect, does a pretty good job searching in Eclipse/CFBuilder:

  \s+(where|set)\s+[a-z_\.]+\s+(like|\=)\s+'?%?#[a-z"_'\.\(\)\+\/]+#%?'?

  
  To do a RegEx search in Eclipse, hit Control/Command + H >> select the File Search tab >> copy the regex pattern above into the Containing text field >> tick the Regular Expression checkbox & un-tick the Case sensitive checkbox. The regex will find the first occurrence of a variable in a cfquery tag which should have cfqueryparam. It doesn't find ones in INSERT queries yet, and I doubt it's 100% accurate otherwise, but it will give you a very good start.

  For more about security, others have done a much better job than I will:
  Pete Freitag's excellent security checklist presentation: http://foundeo.com/security/presentations/hardening-coldfusion.pdf and has a site that will auto-scan for security problems on your ColdFusion site(s): http://hackmycf.com/

  What would you like to see next in this blog series? I'm thinking of a blog entry about development tools: CFEclipse vs. CF Builder vs. Dreamweaver, and ANT for "automated builds", and FogBugz or Jira for Case/Bug management, etc... sound good, or you want something else?

Okay, now let's get down to some coding...

First, you may want to read Part 1 and Part 2 of this blog series.

Next, and I may lose some friends for this, but don't just say the legacy codebase that you're working in "sucks". It might indeed suck, but if you haven't already done so, you might want to check these things first:

1. Click through and really pretend you're a User of the site in production. Does it run slow? Is the user experience really that bad once you learn how to use it?  
2. Are there lot's of errors that prevent users from doing common tasks?
3. Have you asked the author/architect (who wrote most of the original code) to give you some training to explain the "design" of the code and why many of the decisions were made? (he may even have some documentation that he forgot to tell you about)
4. Is the database design so bad that you can't create a database Entity Relationship diagram? There are many database tools for creating ER diagrams based on current designs, and this can be a great way to learn the system.
5. When you make a small change in a reusable piece of code (custom tag, include, common function), does it seem it always breaks something unexpected?
6. Are the variables/files/functions named things like "x", "myVar", "joeBob", or "thisOne"?
7. Is the production system constantly crashing?
8. Does the site/application cause the company to lose lot's of of money?

If you answered "no" to most of these questions, then maybe the system isn't all that bad after all. The most common problem I see with these legacy systems is that new developers don't understand them, and so they quickly jump to the conclusion that "it sucks!". I've done this many times myself, but if I'm really honest it's mostly because I didn't take the necessary steps to really learn the system. And it's hard to keep in mind that it doesn't completely suck as long as it's profitable or serving another important function for your company.

But I digress. You probably want to make your "legacy" code better, so let's start to tackle that. One tendency for us developers is to constantly want to implement the latest and greatest technology that the popular bloggers are advocating: OOP, ColdFuson 9 features, Event Gateways, cfthread, Unit Testing, Automated Builds (via ANT), continuous integration, CF Frameworks, Git instead of SVN/CVS, jQuery, Flex, AIR, ORM, oh my! It gets dizzying, so let's try to focus:

1. What are your biggest "pains" on a daily basis? 
   • Are your CFCs cached in the Application, Server, or Session scopes? And do you have impossible-to-fix errors that are related to those errors? It's probably because not everything is properly Var-scoped. Use http://varscoper.riaforge.org/ on your CFCs and fix them right away.
   • If you do a lot of code releases to production, make sure you're using source control. Most developers know Subversion (SVN), but I hear Git is nice if you're adventurous. Also, get your managers to understand that releasing code to production on a daily or weekly basis is wasting a lot of time, and you should have a longer software release process to improve efficiency.
   • Are your cfquery tags scattered throughout your CFM files? One of the first, relatively easy steps I like to take is to make a project or "rule" that all cfquery/cfstoredproc calls should be wrapped into cffuctions in logically named/grouped CFCs.
   • Are your CFC functions littered with Session, Server, CGI, FORM, URL, Request, Cookie, Client, or Application scope variables? Start with one at a time, and begin to move those out. Pass in Application, Server, and sometimes Request or Session variables to an Init() method when you invoke (or CreateObject()) the CFC. The other scoped variables should be passed in as arguments and functions should not be setting variables directly into any of those scopes, but should pass out something via cfreturn, and the calling page can set the variable(s) accordingly. This will make the code more Unit Testable.
   • If the app is doing a lot of cflocation calls, causing headaches, replace them with my redirect.cfm tag: http://aqlong.posterous.com/a-better-cflocation-tag. You just set a cookie and debugging becomes a lot easier.
   • Convert your Application.cfm files to Application.cfc's 
   • Redo your custom tags so that all data is explicitly passed in as attributes and returned (if necessary) via the Caller scope.
   • If you have a lot of "old school" javaScript code throughout, get up to speed with jQuery. jQuery is to plain javaScript as ColdFusion is to Java... in terms of "ease-of-use" at least. And often times there's a nifty jQuery plugin that does what you need, so I rarely have to write custom functionality for things like form validation or modal windows.
   • Start breaking your huge files with multiple forms on them into smaller files (or custom tags) that can be reused. This is in the spirit of DRY programming: Don't Repeat Yourself.
   • Move your "business logic" and conditional logic (cfif & cfcase) to the top of the "view" CFM files. Then, later you can start moving that logic into CFCs. The "Making Bad Code Good - 2010 edition", with Dan Wilson is excellent for these types of tips: http://experts.na3.acrobat.com/p70807903/
2. Do you have one "mega-application", or lot's of small apps? see my old post on Architecture Scalability for some ideas on how to tackle mega-applications
3. Is your app reasonably secure?
4. Do you feel that the quality of the code would be improved by automated tests: Unit Testing and automated Functional Testing? 

This Part 3 of the series is getting a bit long, so I will tackle #3 & #4 in a future post. Looking forward to some more feedback on my ramblings. ;-)

The first part of this blog series was basically an Intro to what it means to be working in "legacy" code, a bit about my background, and some thoughts on what I'll write about next in this series.

Before I get into code and best practices, etc., I want to discuss sort of an "Assessment phase". By this, I mean a phase where you assess many factors which affect how you will tackle this problem of how to make the best of your legacy ColdFusion codebase. Some factors to consider:

1. How often are releases done?
2. Who is on your development team, and who do you plan to add in the next year or two?
3. What are the skills of your developers, and how much is the "training budget" for improving those skills?
4. Do you have a development team lead who can effectively teach other team members how to use the current system, and how to improve it over time?
5. Does your business deadlines allow for *any* room to make major/sweeping improvements to the code, or are deadlines so tight that you'll only have time to make minor changes as you rapidly add new features?
6. Do you have Quality Assurance, other than expecting each developer to test his/her own code? will you company invest in more/better testing, or do they see it as a waste of time & money?
7. Are there many "mystery" errors and performance problems in the system? 

Let's discuss these one at a time:

1. How often are releases done?
   • Why is this important? Because if you only have short release cycles (i.e. release every 2-4 weeks), you may not be given any time to make major improvements to the code. If you have short release cycles, try to talk your manager into letting you use every 4th cycle just for code improvements and bug fixes. If long cycles, try to budget some time in every release for code improvements; and actually make Cases/Tasks for specific improvements to be made. A good example is a Case to "Add cfqueryparam to all public-facing queries"
2. Who is on your development team, and who do you plan to add in the next year or two?
   • By "who" I mean what level is their ColdFusion knowledge, how many are on your team, and what are their personalities and attitudes towards learning new things and improving quality. If you have any "junior" developers, you should always think about their skill and experience level; you don't want to add complex OO concepts or frameworks when your junior developers are still learning how to write basic CFCs and to use a cfinclude properly. If you only have one or two developers, you can more easily decide what direction you want to go. Are most developers on your team the type that like to learn new things and implement code on the cutting edge, or are they mostly people who like to do things the same old way and stay in their comfort zone? You cannot force a change in this attitude, so you have to take an approach either slower or faster depending on your team's attitude towards newer technology.
3. What are the skills of your developers, and how much is the "training budget" for improving those skills?
   • And just because you team has a cutting edge attitude towards learning doesn't mean that you have the training budget to learn CF9, jQuery, CF Builder, SQL optimization, etc. BTW - here's links to CF & CFB training, jQuery training, and SQL training at www.lynda.com (inexpensive, yet excellent online video training). If there's no training budget, you only have normal work hours to pick up the knowledge, and so you must not expect too much too quickly.
4. Do you have a development team lead who can effectively teach other team members how to use the current system, and how to improve it over time?
   • This is very important. The development "lead" ideally should be someone who communicates very well. If they are spending too much time coding, then they are not spending enough time teaching the other developers how to work in the legacy code or how to improve it. Code Reviews and Pair Programming can help with this situation. You need someone to document and explain the current system and where improvements can be made. And they can lead the team by making sure that Tasks/Cases to improve the system are being worked on as often as possible. 
5. Does your business deadlines allow for *any* room to make major/sweeping improvements to the code, or are deadlines so tight that you'll only have time to make minor changes as you rapidly add new features?
   • You may have little control over this one, as your business may never let go of their old expectations that "time to market" is more important than quality, and that it's best to just get the work done as quickly as possible. But maybe your managers will start to notice that over time as the legacy system gets bigger and bigger, the number of bugs gets higher and higher. If they ever ask you about this, that's your chance to explain that the quality and backbone/"core" of the system needs some improvements so that there won't be so many bugs. It's important to mention that it will be a gradual process, but that within a few months bugs should start to decrease, and in 6-9 months the quality should be significantly higher.
6. Do you have Quality Assurance, other than expecting each developer to test his/her own code? Will you company invest in more/better testing, or do they see it as a waste of time & money?
   
   • If you don't have automated tests (unit tests such as from MXUnit, and automatic functional testing such as with Selenium), then you or someone else is doing a lot of manual testing (logging in, clicking around, etc.) and probably not testing even the majority of your huge app's functionality even before each release. If your developers are doing this manual testing themselves in your staging/testing environment, then they are wasting a lot of man hours that could be better spent *developing*. If you can do some estimates on the "man hours wasted" with manual testing, then maybe you can make a report to give to management to show them how much time could be saved by hiring a QA tester who would write automated functional tests and be responsible for full regression testing prior to each new software release. 
7. Are there many "mystery" errors and performance problems in the system? 
   • The first 2 things that seem to come up for me when I look at a legacy system in a new job are "mystery" errors and performance problems. Before you spend too much time on improving the legacy code and trying to update it to use the newest CF8/9 features, you need a stable system. Often the "mystery" errors are ones that aren't dealt with properly in the error-handling. Search your codebase for <cfcatch type="any"><!--- nothing to see here ---></cfcatch>, and then make sure your onError() function (or CFError tags) grab all the cfcatch info and email it to a developer email that multiple developers can access. Many errors may not be caught by onError() or cferror tags if they are not used properly, or if the errors are *compile-time* (such as CF syntax errors); so, you must make sure that there is a "Site Wide Error Handler" set up in your CF Admin, and it should also email all the error information, and maybe other scopes like FORM, URL, Cookie, Request, etc., to the same email address. Errors in the emails should be watched and anything important should be added as Tasks/Cases to be fixed in an upcoming software release.

     Now if you have performance problems that you don't know how to solve yourself, it's time to consider hiring professional help. The team at http://www.coldfusionsupport.net/ is an excellent start. If you can't hire professional help for some reason, then I recommend SeeFusion or FusionReactor over the built-in CF8+ Monitor, because those other tools aren't tied into CF/Jrun so closely and can capture information about performance even as CF/JRun is dying. Also, many of your problems can be solved by having a good DBA tune your database (especially indexes), and by upgrading your hardware for your application and database servers to 64-bit with extra RAM and plenty of CPU horsepower. Then, allocate more RAM in your jvm.config settings. (If you didn't understand the last few sentences, then that's another reason it would be better to hire good professional help.)

This Part 2 of this blog series may not be what you expected, as you may have wanted to jump into how to improve the code, but I felt discussing this "Assessment phase" was important before we move on. Each company and development team is in a different situation, and no one else can tell you exactly what to do. You must carefully think through all the factors discussed above with your team and write down your conclusions. From there, you can make some plans for how to "refactor" your legacy code most effectively and efficiently within the constraints of your situation. 

So, what do you want to discuss next?

Ever work on "legacy" ColdFusion code? You know, the kind that is homegrown from 1 or 2 developers who cobbled a codebase together starting in ColdFusion 4.5 circa 1999, thousands of files, non-standard naming conventions/directory structures/database designs? 

You might be working in legacy CF code if...

1. 90+% of the reusable code is stuffed into CustomTags
2. all the page layouts are done in html tables
3. the code supports Netscape Navigator 4.0 and IE 5.5, but not any version of Firefox (gotta love HTML 4.0)
4. style is achieved with inline styles (style="color:red;") instead of, what's this, CSS
5. Application.cfm are still hanging around waiting for someone to update them to .CFC files
6. cfform is used heavily
7. CFCs are collections of cffunction tags, with no concept of Var-scoping, much less anything Object Oriented
8. jQuery (or [insert JS library here]) isn't included anywhere
9. there's no consideration for the possibility that some parts of the UI could be done in Flex or AJAX
10. there are no unit tests
11. a "software release" consists of any developer FTP'ing code to a production server whenever there's a "Must have, we'll all die if you don't" bug
12. Request scope is used heavily in favor of the Application scope
13. To increment a database record and INSERT a new record, two queries are wrapped in a cftransaction. The first does a SELECT Max(id)..., and the second uses the ID from the first query to do the INSERT. That's "old school" baby!

(please add your's to the blog comments)

Quickly on my background - Since 2002 (CF 5) I've always worked on legacy CF codebases, with only rare opportunities to do small side projects, as I guess I have a knack for improving these systems without "doing too much" and getting myself fired.  I emphasize high-performance, scalable architectures that are easy for your lowest-common-denominator developer to quickly understand. Most teams don't have the luxury of hire only senior developers, so simplicity, documentation, and clarity are most important in my book for these types of systems. 

So, in this blog series we'll discuss some strategies to upgrade your beloved legacy system in a realistic way. The tendency for the developers who haven't worked with these types of systems before is the want to scrap the whole thing and start over to built the ideal app, OO as possible, with a combination of 2 of your favorite frameworks, graphics redesigned, new CSS, the latest jQuery + jQuery UI, and a beautifully designed database normalized to the n-th degree.

BUT most of us know that will never happen. There were 9,538 man hours put into this old beast, literally by one man. If time stopped, your business didn't have to make new sales or add new features, and some manager actually agreed to let this happen, it would still take far longer than you think for you and a gang of developers to recreate the original system. 

So, where does that leave us? We can still make improvements every day. But how? How should we go about reorganizing the crazy directory structure? How do we move the custom tags to CFCs, where appropriate? Should we introduce a CF framework? How?

I'll attempt to tackle some of these concepts based on my 8 years of experience on this matter, but would love to hear your thoughts and ideas, too. So, leave some comments, and hopefully that will lead into an interesting discussion in Part 2 of this series...

- Aaron