Any software engineer who has some experience under their belt has most likely had to deal with a legacy software system. A legacy system is defined as a computer system that is outdated, but still in use even after newer versions are available.
In web applications, this could mean that an app is running on PHP 7.4, and at the time of writing, PHP 8.5 has just been released. Many security and performance problems have been fixed in recent versions, and it is therefore worthwhile to update.
Keeping a web application updated in terms of security patches is rather high on my list of priorities considering the tremendous scale of the threat landscape the web environment is exposed to. You hear of a new cyberattack on a daily basis, and this puts business at massive financial risk.
As a software engineer specialising in web applications, I've had to deal with quite a number of legacy systems, and some of the systems I've built are now considered legacy. These systems still work and provide a business value; however, it is important to understand what it takes to maintain and upgrade these systems.
With all technology projects, there are trade-offs, and the benefits of keeping a legacy system versus upgrading or rebuilding it should be considered. Rebuilding a 7-year old PHP application might not be worth the money, but upgrading it to a newer PHP version might be a better option. Not everything has to be rebuilt using a shiny new framework or microservices architecture.
In this article, I want to highlight some of my own struggles and how I deal with working with legacy software. It is not simply about having hard programming skills, but also soft skills, because after all, technology is simply useless without people.
Problems
Burnout
The workplace-related illness called burnout is common in the technology industry among programmers, and according to a study by Danilo Monteiro Ribeiro found that one of the dimensions in which changes occur are perceived by developers in a software team's environment is technological instability.
This is not exclusive to legacy systems; however, my focus is only on legacy systems in this article. I'll highlight some examples with which I've had some experience in the past.
I worked on a system that was built with plain old vanilla JavaScript and a backend architecture I was not familiar with. We had to make updates to how user passwords are stored in the system, such as a minimum length, different characters, checking for re-use, because of a cybersecurity audit to ensure insurance compliance.
What I found when exploring the code base was somewhat shocking. Function and variable names didn't provide a clear indication of what they should be used for, and comments we redundant and subjectively specific to the developer working on the code at the time. I frequently found myself getting lost in the code and having to start again to find where a particular piece of data is coming from, mutated, and displayed.
I needed to change the way in which a password is validated in the front end to show the user what they can and cannot enter. I did the change, and out of pure curiosity, I decided to try submitting a blank password, and to my astonishment, it worked!
The backend just accepted it, no complaining, no errors.
When I tried to log in, the front end wouldn't accept a blank password, so I had effectively locked myself out. I laughed so loudly, I couldn't believe the negligence and lack of effort put into this.
The consequences of this instability led to me having to spend more time implementing a feature that should have been there from the very beginning. This caused me some additional stress, on top of the stress already experienced when I read through the code, trying to wrap my head around it.
Some months later, I had to work with an Angular 16 project that uses the legacy Angular Material library. Many things were broken and hacked back together in that application just to make it work, because to update it to a newer version of Angular wasn't (and probably still isn't) feasible for the business.
Implementing new features in this app was an utter painful experience, things unrelated to the feature broke for no apparent reason, and would sometimes take a week to figure out.
All of this just compounded, and I ended up in the emergency room on a Saturday morning at 06h00 with dreadful pain from inflammation in my chest. I was subsequently booked off from work for a week and lost a great deal of progress and productivity.
This is extremely harmful to any business, and I would not recommend leaving a system in such a state for too long. It affects programmers' health and leads to loss of productivity, and eventually, people end up leaving because nothing is being done about it. Hiring can be expensive for any business, especially if it is not necessary if the proper steps had been taken.
Lack of documentation
Documentation is usually a source of contention among software engineers and web developers. We are pressured to perform and meet our deadlines, and therefore skip less high priority tasks such as documentation.
I personally believe that documentation should be a major part of building any system, because programming is such a cerebral activity, and nobody else can see into your mind to understand the thought an decision-making processes that went on while you worked on a bug or a feature.
From past experiences, even I had trouble understanding why I did a particular thing in the way that I did. It might have been a business constraint, or a deadline limitation, which led to me implementing a less than optimal solution, and coming back to it months later takes some extra effort to get back into the flow of things.
Documentation helps to prevent a system from relying too much on a sole developer. A system that truly lasts and is maintainable should have the least amount of dependencies, especially on tacit knowledge. When a developer leaves the company or project, the system can keep existing and serve its business need.
Too much documentation can also mean that a system was poorly architected with many non-standard, or industry and domain standards, and makes it extremely difficult to understand and extend without breaking it in the process.
Outdated, complex and difficult to maintain infrastructure
Sometimes you are handed a piece of software that runs on old versions of source code, such as PHP 7.4 or even older. It might still work, but what if a hosting service decides to stop supporting those versions due to cybersecurity concerns?
This has happened before, and I had to interrupt my current sprint's work to urgently work on upgrading. It wasn't a large code base, but it was nonetheless somewhat painful. Error upon error when trying to update composer dependencies, some are deprecated, and it took more time than it should have if we had just kept it up to date.
In some cases, legacy infrastructure costs more to maintain, because of a lack of expertise and it being such a niche product. For example, a ColdFusion application I had to work on runs on incredibly expensive hardware, not to mention the licensing fees that are applicable to ColdFusion. There also aren't that many skilled ColdFusion developers out there, and the younger generation of programmers will potentially not be willing to learn it due to this, myself included. I just do not see it having any career benefit for me.
Accessing this server is an utter pain, and we have to run a remote desktop session to be able to administer the admin panel. Normally one would do this from a cloud provider's dashboard, or SSH into the server. This slows things down significantly and creates additional dependencies on IT personnel.
How I approach legacy web applications
As a younger, less experienced software professional, I easily became enamoured by fancy new frameworks and wanting to rebuild every website with whatever was hyped the most at the current time.
I made a grave mistake once of building a marketing website as a Vue.js single page application (SPA). SPAs are no good for web applications that rely on search engine traffic, such as this marketing website. I ended up rebuilding it with a Laravel-based content management system with server-rendered pages in HTML and PHP.
Traffic picked up and leads started rolling in.
There is no silver bullet solution for any and all web applications, and it all depends on what you or the client wants to achieve with the application or website.
Understand the underlying business requirements
To deliver a solid solution that benefits the business and their clients in the long run, you absolutely must listen carefully for the types of problems the business is experiencing with the system in it's current state.
Write down the details, ask questions, and empathise with the struggles people who interact with the system.
This helps with forming a big picture of the system and might give you deeper insights on which angle to approach the solution from.
I prefer to identify all of the entities, such as class objects and how they relate to and interact with each other. The deliverable here might be an entity relationship diagram, or a snapshot of what the database looks like. I've written about databases previously and how important they are in any application.
Use your IDE's code inspection tools
I use Jetbrains' IDEs to write my code in and I absolutely love them. They are the most comprehensive and robust tools in my kit and include everything I need.
When I am working with a web application, I mainly use PhpStorm, and have tools like SonarQube and Snyk configured.
For PHP-based projects, you can use PHPStan, which is a PHP static analysis tool to find bugs in the legacy code base. This helps identify weak points in the system so that you and your team can prioritise and fix them.
If you're pedantic about following conventions when using Laravel, I highly recommend using Laravel Pint, which is automatically installed with every new Laravel app at the time of writing. It is a PHP code style fixer, ensuring your code stays clean and consistent.
There is nothing worse than having to work with an inconsistent codebase!
Use AI to help you debug and understand the code
I have a bit of a love-hate relationship with artificial intelligence-based coding assistants. Numerous times they've slowed me down, but for legacy systems, they can be a massive boost.
I would drop a piece of code that is extremely difficult to understand, ask it to reformat it with better naming conventions and variable names, and run it in the code base to see if it generates the same results.
Other times I would drop an error message into the AI chat interface and help me figure it out.
Googling often takes much longer, and having AI chats that are connected to the internet speeds things up significantly.
I am, however, somewhat careful of not relying too much on AI to help me understand code. I do not want to become lazy in my thinking.
Respect the previous authors, they were only doing their jobs to the best of their abilities
I've learned from experience that programming is an art, and each of us have our own unique way of solving a problem if it is an uncommon problem.
Judging someone by how they write their code is sometimes unfair, because we might not be aware of the constraints those people had to operate in, be it infrastructure limits or extremely tight deadlines set my project managers who don't understand the technical complexity of the system.
I've been there myself and have developed a lot of empathy for people in the same role as I. We often do not have any say in how things are done, nor are we included during the decision-making process.
Sometimes you can see when a developer was inexperienced, but it is important to realise that we have all been at that point, and it is unnecessary to act like an arrogant elitist and lose your temper over it.
Communicate with your team and stakeholders
For any work, it is highly important and valuable to communicate, especially when you see something that is wrong, or if you are unsure of something.
Staying quiet is never the correct option to choose, as this leads to mismanagement of the project later on.
Learning how to talk to people to meet them half way is an incredibly valuable skill, and will also help you negotiate to get the best possible results, the one you know will work.
Conclusion
Legacy web applications can be a nightmare to deal with, but it doesn't have to be. With the right mindset and tools in your arsenal, you can effectively manage any legacy web application project without too much pain and suffering.
I hope this post has helped you in some way, and if you believe I am a good fit to help you with your legacy website or web application, I'd be happy to have a chat with you. You can reach me on my email address: work (at) chilldsgn.com