Maintaining Badly Written Legacy Code

You have been handed a project or partly developed application to support. Due to prior deadlines, restricted budgets, limited developer skill, multi-developer miscommunication or just plain laziness from some previous developers you have been handed a maintenance nightmare. What steps can you take to improve this situation.

It is likely that you will not get the time to rewrite or refactor what is basically a mess, so small steps and a plan of action is needed:

1. Do you have a prior list of complaints or help-desk calls that provide an overview of problems and priorities?
2. Does the code have exception or error handling?
3. How appropriately named are the variables? I have seen code with variables named aThingList and aColList.
4. Is the code laid out in a way that makes it easy to understand the flow of instructions? I have seen code that was completely left-aligned making reading to understand it extremely difficult.
5. Is there an infinite number of exponential loops within the code?
6. Have you been left adequately written documentation about the application and any code and design decisions that were made.

First you need to tackle any commonly reported application problems. This often means finding the algorithmic cause of problems. Ideally you will be able to run a script over an uncompiled version of the application and replicate the error. Make a copy of any data sources the applications uses so that you can safely manipulate data without affecting the live system the users are using. If you can break into the code during an error or an exception then do so and step through the code line by line until you find the error.

If you cannot break into the code whilst the application is running then you will have to rely upon tracing code movement via a message notification, either using message boxes, writing to a file or writing the algorithm results to a makeshift debug screen. A notification at the entrance of a routine which includes the routine name and the time entered would be useful.

Once you have determined where the error is occurring you will need to determine why?

Is the data causing the problem? The best way to solve this problem is to improve data quality at the datasource. Perhaps an uploaded data file is not up to scratch. Perhaps the user is entering an unacceptable value. Even though the latter could be blamed upon the application's lack of built-in ability to check user input, decisions made during it's previous development phase could have put the responsibility upon the user to enter correctly formatted data which would make this a training issue not a data issue.

== ERROR-HANDLING ==
I have seen numerous applications' code without any kind of exception/error-handling. You need to enter exception/error-handling into routines you know have errors and extraneously long routines. Within error notification you will need to display the routine name, error number and error message. For more information upon error handling see my article .

== BADLY NAMED VARIABLES ==
Usually there is not much you can do about a situation where the variable names are less than adequately descriptive of their purpose. Search and replace functionality may help you but usually will not discriminate between variables sharing the same name, in different areas of the cod,e that are used for different purposes. In fact, the renaming of an ambiguous name to a more purposeful name may complicate the understanding of the code where other variables of the same name are affected. The best practice is to write a comment next to the variable explaining it's use for any particular routine within which it is found.

== CRUMMILY LAID OUT CODE ==
Either the code is all left-aligned or dischevelled: Reading badly laid out code is difficult in either case. If you have an editor that automatically indents code based upon language, cut and paste the code into your editor, realign the code and paste back into the application. If you do not have an editor and will be working with this code for some time, perhaps a quickly typed script to clean the code is in order. This is not as hard as it sounds. Basically all the script needs to do is count and add tab spaces whilst reading in each line of the code. If for example your script finds a While statement it adds a tab to the front of the next lines of code it reads in until it finds a Wend statement.

If an application's existing code is particularly ugly and your job is only to add functionality to the application you may consider either removing the old code to a library so you will not have to look at it or build a module as an interface to the old code. The benefit of this is that you will only have to modify your interface should you need to make changes in the future. A added bonus is that you can comment your interface and remove your reputation from the extant disaster behind your it.

== INFINITE DO, WHILE, FOR LOOPS ==
My pet hate! If the code is not inextricably entwined within looping statements then try to reduce the complexity of a routine by extracting algorithms from the loop statements and placing the functionality within separate, smaller routines.

Document your changes via comments within the code or preferably use version tracking software to capture your changes.

== PROCESS IMPROVEMENT ==
Before embarking upon a plan of gradual improvement you need to do some investigation and find out whether there are any projects underway that could replace the application you have been handed. You do not want to waste time and effort patching up an application that will soon be replaced or defunct. Perhaps there are addins to other applications that can provide the same service to the users. Your goal is to get rid of the application if you can or reduce its negative impact upon workload (due to badly written algorithms) by farming out its tasks to better written and more stable applications. Maintenance is an expensive and time-consuming process for badly written applications.

If you cannot rid yourself of the application then write down some steps of improvement, for example; introduce exception/error-handling where it is lacking. Break down seriously long routines. Rewrite extremely bad legacy code that fails to live up to expectations. Remove ugly code to a separate library and access it's functionality by a cleanly written interface. Perhaps you could introduce user input testing or format masks to force consistent data entry.

Sometimes an application produces reports with spurious results due to poorly devised calculations and inadequate testing of SQL string results. Provide users with data dumps in comma separated value (csv) files so they can build their own reports using spreadsheets and charting software ().

Do not be shy in discussing with your users the fact that you have been handed a lemon of an application, they will more than likely agree with you. Inform them on how you intend to implement a plan of process improvement and ask them for their thoughts and ideas. Remind them that it will be a gradual process and involve them in the development and testing. This is called the winning of hearts and minds! This concepts works because it is an inherently genuine and honest approach to improving the situation for your users and yourself.

Do not be disheartened by any user's cynicism towards the services and plans you plan to offer them; When an application produces bad results for any period of time, prior promises upon which the previous developer was supposed to deliver have been broken and it is the user who suffers the results of those broken promises.

Lastly! Expedient support to users' problems will be extremely appreciated even if your plan of improvement is slowed because of it.