The term legacy code conjures thoughts of dread in developers everywhere. It’s code that’s perceived (justly or unjustly) to be tightly-coupled, hard to understand, hard to change, and just plain out-dated. It’s an immovable object.
The reality is, legacy code is everywhere, and it isn’t going anywhere. So why not make it better, and make our lives working with it everyday easier?
This isn’t just about upgrading your libraries and frameworks, it’s also about modernizing the code itself and its use of those libraries/frameworks over time, which in turn, makes future improvements and upgrades easier.
But upgrades can be hard work and they do carry risks, so teams often put them off as long as possible. It’s a common best practice to avoid “big bang”, high-risk changes by instead making small incremental and low-risk changes over time. This allows you to minimize risk by spreading changes out over several releases, and makes isolating issues much easier when things do go wrong.
Big framework upgrades for example, should be no different. Often these upgrades also require updating a lot of existing code, for example, meeting minimum library version compatibility requirements or re-factoring out use of previously deprecated code which has now been removed. Why include the framework upgrade and all the upgrade-related code changes in the same release? Foresight and an ongoing mentality of modernization are required in order to prevent these upgrades from becoming a really painful process. This is one of the things that makes legacy code feel more and more legacy; a fear of change and helplessness to improve. It’s a vicious cycle.
By managing modernization in small and steady increments as a regular maintenance activity, these upgrades become much less risky, and in some cases, can be close to non-events. The remainder of this post goes over some tips I’ve found about how to go about it. I successfully employed this on a large legacy codebase recently migrating from an aging Spring 3 framework codebase to the latest Spring 4 release, with some key improvements along the way.
Why you should always be modernizing the libraries/frameworks in your codebase
There are of course obvious reasons to do this, including developer productivity/happiness/retention, performance improvements and avoiding being on end-of-life release versions (no more bug fixes, security patches, etc.). But then there are other more subtle reasons that people don’t think about, but are equally important:
- Many people learn by example. Junior developers should see exemplary code. There’s also a strong mental bias towards using things that are already known to work. In both of these cases, this can lead to bad or old code and patterns being replicated and proliferated around your codebase.
- There are also other more subtle forms of copying, like build scripts or configuration. These are especially important in multi-repository codebases. You should stay on top of these as well.
So when you do upgrade, don’t just do the bare minimum to get on the new version. Actively modernize the code to use the new API’s, techniques and other improvements. Increase the chances that proliferations that do occur are of good patterns and code, not bad ones.
As a very simple example to illustrate the point; When you perform an upgrade from Spring 3.x to 4.x, you can eliminate the need to use default constructors in your spring beans. If a developer is unfamiliar with this improvement and they come across other code in the codebase which has a default constructor even in the new version, they might assume it’s still necessary. Suddenly you find more default constructors popping up in new classes being created around your codebase..
How to upgrade
Ok, so you’re convinced (I hope). How do you go about doing upgrades in the least painful way?
Obviously, the first thing you should do is look at release notes for notable changes. I like to create one or more throwaway/scratch branches to discover unknown/unforeseen issues and ticket them separately and independently where possible. This can really help map out an upgrade and come up with the best plan of attack in terms of mitigating risk.
I like to make small/easy changes first to clear away the simple stuff and get clarity on the more complex changes. It also helps me see things from different angles and find bugs. And as always, review your own PR’s.
Your goal should be to make upgrades as low risk as possible. Obviously the upgrade itself presents some risk, but generally speaking if it’s of high quality, you can expect that it has been thoroughly tested in many scenarios by the authors.
Another important and related maintenance activity is staying on top of deprecation notices. A good library/framework will first deprecate something for at least one release before it is completely removed. A library respecting semantic versioning will only do this in a major version (i.e. one with breaking API changes). This will mean the newer alternative is available in a current version you are already using. If you stay on top of deprecation notices, and use the newest API, you may simply be able to do a version bump in your build file and have that be your only change. This is where you want to be.
For example, in a Spring 3.x codebase, use of deprecated classes like CommonsClientHttpRequestFactory and TimerFactoryBean already have alternative counterparts ready to use in HttpComponentsClientHttpRequestFactory and ScheduledExecutorFactoryBean, respectively. In many of these cases, the new classes are drop-in replacements for the old, or require only minor code changes. After these re-factors, this code remains unchanged in the version bump to 4.x.
Post-upgrade: Identify modernization opportunities
Once you’ve upgraded, you probably already have a laundry list of new improvements you would like to leverage that you already know about. Ticket and backlog them as tech debt. But dig a little deeper. Spend a little time familiarizing yourself with all the changes and improvements and map out which you would like to explore further.
In the case of our Spring upgrade, there were a slew of new improvements to leverage from the core container, to ease of testing, improved messaging support, not to mention bumping the major versions of many other spring umbrella projects (spring security, spring integration, spring batch, etc.) and the list goes on.
Undertaking some of these modernization efforts can go a long way towards producing more of that exemplary code in your codebase.
Then, Look & Plan ahead. Now!
Continuing with our Spring 4 upgrade example, why not start looking ahead to Spring 5? It’s M4 at the time of this writing, but how about making a plan now? The upgrade raises minimum versions of many dependencies. Are you on Hibernate 5 yet? What about Servlet API 3.1? You get the picture.
If you have more interest in the topic of improving legacy code, you might want to check out this great software daily podcast episode on the subject too for some inspiration.
I cannot agree more on one of the reasons of modernizing, i.e. developer happiness or retention. Recently I encountered a company whose tech stack is ages old, though they have excellent compensation. I refused to apply to its job posting for my resume would be so ugly!
That being said, switching to a totally new technology is always risky and we usually cannot foresee the dangers far ahead. At least I encountered the following two typical stories:
* Grails framework is so fancy and cool, but it is so weak in static checking because of the design of Groovy language. Even a typo in method name can only be found during runtime; also, only developers fully versed in Spring and Hibernate can harness its complexity; One company bases its backend purely on Grails but good developer to harness the complexity is so difficult to find. At a result, they formed the habit to ignore testing code in most cases;
* Spring framework seems inevitable but one company I worked in still relies on static dependency while adopting it; loose coupling and henceforth better testability is the gist of Spring framework. I failed to come up with a real integration testing case just because of the ubiquitous static dependencies; AOP or declarative transaction demarcation is another gem of Spring framework, but they still rely on home-grown transaction implementation rather than the far far better Spring transaction. I totally agreed on the importance of modernizing library/framework, but sometimes switching mindset is more fundamental while adopting a modern library/framework for the first time.