How Cleaning Up Projects Eliminates Technical Debt and Improves Developer Experience

Making sure your project is nice and tidy will eliminate a world of problems which you do not have to solve.

Content

• Intro
• Legacy hell
• The cleanup
• Lessons learned
• Conclusion

Intro

As software developers, we often inherit projects with a lot of technical debt, legacy code, and poor developer experience. Sometimes, the sheer number of problems in a codebase makes it easy to accept the status quo and ignore the issues, but this only leads to more software maintenance headaches and lower code quality over time. For me, working in a messy project goes against everything I believe in as a developer and makes it harder to deliver value.

This is a story of how I tackled a legacy project, cleaned up the codebase, reduced technical debt, and improved both the CI/CD pipeline and the overall developer experience. Here’s what I learned about project management and code quality along the way.

Legacy hell

Recently, I worked on a legacy project that had been around for years, with multiple teams and developers leaving their mark on the codebase. The result was a patchwork of different coding styles, outdated documentation, and a lack of clear standards. Deploying even to the DEV environment took 30 minutes, and tools like SonarQube for code analysis were impossible to integrate. Linting rules conflicted, code formatting was inconsistent, and the Webpack configuration was overly complex. All of this made the project hard to maintain, difficult to update, and a prime example of technical debt and poor software maintenance.

On top of these issues, the project suffered from legacy code bloat—about 90% of the code wasn’t even used for the current use cases. This added unnecessary cognitive complexity and made every change riskier. After forking the repository for my team, a code cleanup and refactoring effort became inevitable to restore code quality and improve developer experience.

The cleanup

I won’t go into the details of every change, but the main focus was deleting unused folders and files to reduce technical debt and improve codebase health. Here are the before/after numbers and the approach I used to ensure the application still worked after major code removal.

My cleanup strategy was iterative: first, I deleted large groups of obviously unused folders. Next, I removed individual files that were no longer needed. The third phase (which I skipped due to time constraints) would have targeted unused helper functions and dead code within the remaining files. This approach was inspired by Peter Kofler (aka Code Cop), whose advice on code quality and refactoring was invaluable. I also relied on simple manual UI tests and NPM scripts after each deletion to confirm nothing was broken, followed by CI/CD pipeline runs to catch any issues between local and DEV environments.

Lessons learned

Don’t be afraid to break things. When a project is weighed down by technical debt and legacy code, it’s almost impossible to make things worse. Sometimes, bold refactoring is the only way to restore code quality and maintainability.

Just do it. I knew a cleanup was needed soon after joining the project. Once I understood the codebase, it was clear that simplifying and removing technical debt would benefit everyone.

Remove code iteratively (folders, files, methods). Don’t waste time making tiny changes and hoping nothing breaks. Remove large sections of unused code, then test and verify. This approach is more effective for improving codebase health and developer experience.

Deploy often. Frequent deployments and CI/CD pipeline runs after each cleanup step helped me catch issues early. Manual UI tests and NPM scripts were essential for validating changes. Thank goodness for Git and version control!

Fix the broken windows. If you let small problems linger, they multiply. Whether it’s a broken window or a hole in your boat, ignoring code quality issues leads to bigger problems. Don’t let your standards slip — address technical debt and maintain clean code practices.

Removing unused code didn’t solve every problem in this legacy project, but it made a huge difference. It also paved the way for further improvements, like updating dependencies, adding TypeScript, and using modern JavaScript features. My hope is that this story encourages you to tackle technical debt and prioritize code quality in your own projects. Developers should always advocate for maintainable, high-quality code, even when deadlines and priorities compete for attention.

Conclusion

I’m not one to brag, but cutting CI/CD pipeline times in half just by removing unnecessary code and technical debt felt like a major win. No other performance optimizations were needed — just a focus on code quality and project cleanup.

One big takeaway from this experience is how to quickly evaluate the health of a legacy codebase. Look at your CI/CD times, identify what’s outside your control, and spot the bottlenecks. Check for TODO comments, lint warnings, and console errors in both Node and the browser. Don’t forget to review outdated dependencies and see how old they are. These metrics are key indicators of technical debt and software maintenance needs.

Have you ever had to clean up a legacy project or tackle technical debt? What was your approach? I’d love to hear your experiences — feel free to reach out and share your story.