Modernize Legacy Code in Production – Rebuild your Airplane Midflight without Crashing

I spent over a decade as a guide working for dozens of firms in lots of fields and pursuits. The range of every code base is large. This text will attempt to outline common guidelines for modernizing legacy code that will hopefully apply to all. But it surely comes from the angle of a Java developer.

When penning this, my major focus is on updating an outdated Java 6 period model J2EE code to the extra fashionable Spring Boot/Jakarta EE code. Nonetheless, I don’t wish to go into the code and attempt to hold this generic. I focus on COBOL and comparable legacy programs too. Many of the overarching pointers ought to work for migrating some other sort of codebase too.

Rewriting a venture isn’t an immense problem, principally – nonetheless, doing it whereas customers are actively banging in opposition to the present system with out service disruption?

That requires quite a lot of planning and coordination.

Why Modernize?

I don’t suppose we should always replace tasks for the sake of the “newest and biggest”. There’s a cause widespread legacy programs like COBOL are nonetheless used. Beneficial code doesn’t lose its shine simply due to age. There’s rather a lot to be stated for “code that works”. Particularly if it was constructed by a whole lot of builders many years in the past. There’s quite a lot of hidden enterprise logic mannequin information in there…

Nonetheless, upkeep can typically develop into the bottleneck. You may want so as to add options making the method untenable. It’s laborious to search out one thing in hundreds of thousands of strains of code. The flexibility to leverage newer capabilities may be the ultimate deciding issue. It may be attainable to create the same venture with out the identical complexities, due to newer frameworks and instruments.

We shouldn’t take a choice to overtake present code that’s in manufacturing frivolously. It’s essential to create a plan, consider the dangers and have a option to again out.

Different causes embrace safety, scalability, finish of life to programs we depend on, lack of expert engineers, and so on.

You normally shouldn’t migrate for higher tooling however higher observability, orchestration, and so on. Are an amazing profit.

Modernization provides you the chance to rethink the unique system design. Nonetheless, this can be a dangerous proposition, because it makes it fairly simple to introduce refined behavioral variations.


Earlier than we head to preparations, there are a number of deep challenges we have to evaluation and mitigate.

Entry to Legacy Supply Code

Generally, the supply code of the legacy codebase is now not workable. This may imply we are able to’t add even primary options/performance to the unique venture. This may occur due to many causes (authorized or technical) and would make migration more durable. Unfamiliar code is an immense downside and would make the migration difficult, though attainable.

It’s quite common to show inner calls within the legacy system to allow clean migration. E.g. we are able to present fallback capabilities by checking in opposition to the legacy system. An outdated product I labored on had a customized in home authentication. To maintain compatibility throughout migration, we used a devoted net service. If consumer authentication failed on the present server, the system checked in opposition to the outdated server to supply a “seamless” expertise.

That is necessary through the migration part however can’t all the time work. If we don’t have entry to the legacy code, instruments akin to scraping may be the one recourse to get good backwards compatibility through the migration interval.

Generally, the supply is now not obtainable or was misplaced. This makes preparation more durable.

Incapability to Isolate Legacy System

To be able to analyze the legacy system, we’d like the flexibility to run it in isolation so we are able to take a look at it and confirm its behaviors. This can be a widespread and necessary apply, however isn’t all the time attainable.

E.g. a COBOL codebase working on devoted {hardware} or working system. It may be troublesome to isolate such an atmosphere.

That is in all probability the largest downside/problem you may face. Generally an exterior contractor with area experience might help right here. If so, it’s value each penny!

One other workaround is to arrange a tenant for testing. E.g. if a system manages payroll, arrange a pretend worker for testing and carry out the duties mentioned beneath in opposition to manufacturing. This is a gigantic hazard and an issue, so this case is way from superb and we should always take it provided that no different choice exists.

Odd Codecs and Customized Shops

Some legacy programs may depend on deeply historic approaches to coding. An awesome instance is COBOL. In it, they saved numbers based mostly on their type and are nearer to BCD (Java’s BigDecimal is the closest instance). This isn’t dangerous. For monetary programs, that is truly the suitable option to go. But it surely may introduce incompatibilities when processing numeric knowledge which may forestall the programs from working in parallel.

Worse, COBOL has a posh file storage answer that isn’t an ordinary SQL database. Transferring away from one thing like that (and even some area of interest newer programs) will be difficult. Fortunately, there are answers, however they may restrict the practicality of working each the legacy and new product in parallel.


Earlier than we have to even contemplate an endeavor of this kind, we have to consider and put together for the migration. The migration might be painful no matter what you do, however this stage permits you to shrink the scale of the band support it is advisable to pull off.

There are various common guidelines and setups it is advisable to observe earlier than present process a code migration. Every one in all these is one thing it is advisable to be deeply acquainted with.

Function Extraction

When now we have an extended working legacy system, it’s nearly unattainable to maintain observe of each function it has and the position it performs within the closing product. There are paperwork, however they’re laborious to learn and undergo when reviewing. Challenge trackers are nice for followup however they aren’t nice maps.

Discovering the options within the system and those which are “truly used” is problematic. Particularly once we wish to concentrate on trivialities. We wish each small element. This isn’t all the time attainable but when you should utilize observability instruments to point what’s used it could assist very a lot. Migrating one thing that isn’t used is irritating and we’d wish to keep away from it, if attainable.

This isn’t all the time sensible as most observability instruments that present very nice grained particulars are designed for newer platforms (e.g. Java, Python, Node and so on). However you probably have such a platform akin to an outdated J2EE venture. Utilizing a software like Lightrun and putting a counter on a particular line can let you know what’s used and what in all probability isn’t. I focus on this additional beneath.

I typically use a spreadsheet the place we listing every function and minor habits. These spreadsheets will be big and we would divide them based mostly on sub modules. This can be a course of that may take weeks. Going over the code, documentation and utilization. Then iterating with customers of the appliance to confirm that we didn’t miss an necessary function.

Reducing corners is simple at this stage. You may pay for them later. There have been instances I assigned this requirement to a junior software program developer with out correctly reviewing the output. I ended up regretting that, as there have been circumstances the place we missed nuances inside the documentation or code.

Compliance Assessments

That is a very powerful side for a migration course of. Whereas unit assessments are good, compliance and integration assessments are essential for a migration course of.

We’d like function extraction for compliance. We have to go over each function and habits of the legacy system and write a generic take a look at that verifies this habits. That is necessary each to confirm our understanding of the code and that the documentation is certainly right.

As soon as now we have compliance assessments that confirm the present legacy system, we are able to use them to check the compatibility of the brand new codebase.

The basic problem is writing code which you can run in opposition to two fully totally different programs. E.g. Should you intend to alter the consumer interface, adapting these assessments can be difficult.

I’d advocate writing the assessments utilizing an exterior software, perhaps even utilizing totally different programming languages. This encourages you to think about exterior interfaces as an alternative of language/platform particular points. It additionally helps in discovering “bizarre” points. E.g. We had some incompatibilities due to minute variations within the HTTP protocol implementation between a brand new and legacy system.

I additionally counsel utilizing a very separate “skinny” adapter for the UI variations. The assessments themselves should be similar when working in opposition to the legacy and the present codebase.

The method we take for take a look at authoring is to open a difficulty inside the problem tracker for each function/habits within the spreadsheet from the earlier step. As soon as that is carried out, we shade the spreadsheet row in yellow.

As soon as we combine a take a look at and the problem is closed, we shade the row inexperienced.

Discover that we nonetheless want to check components in isolation with unit assessments. The compliance assessments assist confirm compatibility. Unit assessments test high quality and in addition full a lot quicker, which is necessary to productiveness.

Code Protection

Code protection instruments won’t be obtainable in your legacy system. Nonetheless, if they’re, it is advisable to use them.

The most effective methods to confirm that your compliance assessments are intensive sufficient is thru these instruments. It’s essential to do code opinions on each protection report. We must always validate each line or assertion that isn’t coated to verify there’s no hidden performance that we missed.

Recording and Backup

If it’s attainable, document community requests to the present server for testing. You should use a backup of the present database and the recorded requests to create an integration take a look at of “actual world utilization” for the brand new model. Use reside knowledge as a lot as attainable throughout growth to stop surprises in manufacturing.

This won’t be tenable. Your reside database may be entry restricted or it may be too huge for utilization throughout growth. There’s clearly privateness and safety points associated to recording community visitors, so that is solely relevant when it will probably truly be carried out.


One of many nice issues about migrating an present venture is that now we have an ideal sense of scale. We all know the visitors. We all know the quantity of knowledge and we perceive the enterprise constraints.

What we don’t know is whether or not the brand new system can deal with the height load througput we require. We have to extract these particulars and create stress assessments for the essential parts of the system. We have to confirm efficiency, ideally evaluate it to the legacy to verify we aren’t going again when it comes to efficiency.


Which components ought to we migrate and in what manner?

What ought to we goal first and the way ought to we prioritize this work?

Authentication and Authorization

Many older programs embed the authorization modules as a part of a monolith course of. This can make your migration difficult whatever the technique you are taking. Migration can be an incredible alternative to refresh these outdated ideas and introduce a safer/scalable method for authorization.

A standard technique in circumstances like that is to ship a consumer to “enroll once more” or “migrate their accounts” when they should use the brand new system. This can be a tedious course of for customers and can set off quite a lot of help points e.g. “I attempted password reset and it didn’t work”. These kinds of failures can occur when a consumer within the outdated system didn’t carry out the migration and tries to reset the password on the brand new system. There are workarounds akin to explicitly detecting a particular case akin to this and redirecting to the “migration course of” seamlessly. However friction is to be anticipated at this level.

Nonetheless, the advantage of separating authentication and authorization will assist in future migrations and modularity. Consumer particulars within the shared database is generally one of many hardest issues emigrate.


When coping with the legacy system, we are able to implement the brand new model on high of the present database. This can be a widespread method and has some benefits:

  • Prompt migration – that is in all probability the largest benefit. All the info is already within the new system with zero downtime
  • Easy – that is in all probability one of many best approaches to migration and you should utilize present “actual world” knowledge to check the brand new system earlier than going reside

There are additionally a number of severe disadvantages:

  • Information air pollution – the brand new system may insert problematic knowledge and break the legacy system, making reverting unattainable. Should you intend to supply a staged migration the place each the outdated and new programs are working in parallel, this may be a difficulty
  • Cache points – if each programs run in parallel, caching may trigger them to behave inconsistently
  • Persisting limits – this carries over limitations of the outdated system into the brand new system

If the storage system is fashionable sufficient and highly effective sufficient, the method of migrating the info on this manner is sensible. It removes, or no less than postpones, a problematic a part of the migration course of.


The next three ideas are on the root of utility efficiency. Should you get them proper, your apps might be quick:

  1. Caching
  2. Caching
  3. Caching

That’s it. But only a few builders use sufficient caching. That’s as a result of correct caching will be very difficult and might break the only supply of data precept. It additionally makes migrations difficult, as talked about within the above part.

Disabling caching throughout migration won’t be a practical choice, however decreasing retention may mitigate some points.


There are a number of methods we are able to handle a large-scale migration. We are able to have a look at the “huge image” in a migration e.g. Monolith to Microservices. However as a rule, there are extra nuanced distinctions through the course of.

I’ll skip the plain “full rewrite” the place we immediately substitute the outdated product with the brand new one. I feel it’s fairly apparent and all of us perceive the dangers/implications.

Module by Module

Should you can decide this technique and slowly substitute particular person items of the legacy code with new modules, then that is the perfect option to go. That is additionally one of many largest promoting factors behind microservices.

This method can work nicely if there’s nonetheless a workforce that manages and updates the legacy code. If one doesn’t exist, you might need a significant issue with this method.

Concurrent Deployment

This may work for a shared database deployment. We are able to deploy the brand new product to a separate server, with each merchandise utilizing the identical database as talked about above. There are various challenges with this method, however I picked it typically, because it’s in all probability the best one to start out with.

Because the outdated product remains to be obtainable, there’s a mitigation workaround for present customers. It’s typically advisable to plan downtime for the legacy servers to power present customers emigrate. In any other case, on this situation, you may find yourself with customers who refuse to maneuver to the brand new product.

Hidden Deployment

On this technique, we cover the present product from the general public and arrange the brand new system as a substitute. To be able to ease migration, the brand new product queries the outdated product for lacking info.

E.g. if a consumer tried to login and didn’t register within the system, the code can question the legacy system emigrate the consumer seamlessly. That is difficult and ideally requires some adjustments to the legacy code.

The big profit is that we are able to migrate the database whereas holding compatibility and with out migrating all the info in a single fell swoop.

A serious draw back is that this may perpetuate the legacy code’s existence. It’d work in opposition to our growth objectives on account of that.


You completed writing the code. We’re prepared to drag the set off and do the migration… Now we have to replace the customers that the migration goes to happen. You don’t need an offended buyer complaining that one thing all of the sudden stopped working.


If attainable, carry out a dry run and put together a script for the migration course of. After I say script, I don’t imply code. I imply a script of obligations and duties that must be carried out.

We have to confirm that every part works because the migration completes. If one thing is damaged, there must be a script to undo every part. You’re higher off retreating to redeploy one other day. I’d moderately have a migration that fails early that we are able to “stroll again” from than having one thing “half-baked” in manufacturing.


For my part it’s best to use a smaller workforce for the precise deployment of the migrated software program. Too many individuals can create confusion. You want the next personnel on board:

  • IT/OPS – to deal with the deployment and reverting if essential
  • Assist – to discipline consumer questions and points. Increase flags in case a consumer studies a essential error
  • Builders – to determine if there are deployment points associated to the code
  • Supervisor – we’d like somebody with prompt decision-making authority. Nobody desires to drag a deployment. We’d like somebody who understands what’s at stake for the corporate

There’s a bent to make a code repair to get the migration by way of. This works OK for smaller startups and I’m fairly responsible of that myself. However when you’re working at scale, there’s no option to do it. A code change carried out “on the spot” can’t move the assessments and may introduce horrible issues. It’s in all probability a nasty concept.


The axiom “don’t deploy on a Friday” may be a mistake for this case. I discover Fridays are an incredible migration interval once I’m prepared to sacrifice a weekend. Clearly I’m not advocating forcing individuals to work the weekend. But when there’s curiosity in doing this (in alternate for trip time) then low visitors days are the perfect time for making main adjustments.

Should you work in a number of time zones, builders within the least lively time zone may be finest to deal with the migration. I’d counsel having groups in all time zones to maintain observe of any attainable fallout.

Agility in these conditions is essential. Responding to adjustments shortly could make the distinction between reverting a deployment and soldering on.

Staged Rollout

With small updates, we are able to stage our releases and push the replace to a subset of customers. Sadly, once we do a serious change, I discover it extra of a hindrance. The supply of errors turns into more durable to differentiate you probably have each programs working. Each programs must run concurrently, and it would trigger extra friction.

Publish Migration

A few weeks had handed, issues calmed down, and the migration labored. Ultimately.

Now what?

Retirement Plan

As a part of the migration, we introduced with us a big set of options from legacy. We in all probability want a few of them, whereas some others won’t be essential. After ending the deployment, we have to determine on the retirement plan. Which options that got here from legacy needs to be retired and the way?

We are able to simply see if we use a particular technique or if it’s unused within the code. However are the customers utilizing a particular line of code? A particular function?

For that, now we have observability.

We are able to return to the function extraction spreadsheet and evaluation each potential function. Then use observability programs to see what number of customers invoke a function. We are able to simply do this with instruments like Lightrun by putting a counter metric within the code (you may obtain it at no cost here). In accordance with that info, we are able to begin narrowing the scope of options utilized by the product. I mentioned this earlier than so it won’t be as relevant if this performance labored within the legacy system.

Much more necessary is the retirement of the working legacy. Should you selected a migration path by which the legacy implementation remains to be working, that is the time to determine when to drag the plug. Moreover prices, the safety and upkeep issues make this impractical for the long term. A standard technique is to close down the legacy system periodically for an hour to detect dependencies/utilization we would not pay attention to.

Instruments akin to community screens may assist gauge the extent of utilization. If in case you have the flexibility to edit the legacy or a proxy into the legacy that is the time to gather knowledge in regards to the utilization. Detect the customers that also rely upon that and plan the e-mail marketing campaign/course of for shifting them on.

Use Tooling to Keep away from Future Legacy

A contemporary system can take pleasure in most of the newer capabilities at our disposal. CI/CD processes embrace subtle linters that detect safety points, bugs and carry out opinions which are far superior to their human counterparts. A code high quality software could make an enormous distinction to the maintainability of a venture.

Your product must leverage these new instruments so it received’t deteriorate again to legacy code standing. Safety patches get delivered “seamlessly” as pull requests. Modifications get implicit opinions to eradicate widespread errors. This permits simpler long-term upkeep.

Sustaining the Compliance Testing

After the migration course of, individuals typically discard the compliance assessments. It is sensible to transform them to integration assessments if attainable/essential, but when you have already got integration assessments, it may be redundant and more durable to take care of than your commonplace testing.

The identical is true for the function extraction spreadsheet. It’s not one thing that’s maintainable and is simply a software for the migration interval. As soon as we’re carried out with that, we should always discard it and we shouldn’t contemplate it as authoritative.


Migrating outdated code is all the time a problem, as agile practices are essential when taking over this endeavor. There are such a lot of pitfalls within the course of and so many factors of failure. That is very true when that system is in manufacturing and the migration is important. I hope this listing of ideas and approaches will assist information your growth efforts.

I feel ache on this course of is unavoidable. So is a few failure. Our engineering groups should be agile and attentive to such circumstances. Detect potential points and handle them shortly through the course of. There’s much more I might say about this, however I wish to hold it common sufficient so it’s going to apply to wider circumstances. If in case you have ideas on this, attain out to me on twitter to let me know.

Add a Comment

Your email address will not be published. Required fields are marked *