Jean Hsu
Jean Hsu
Dec 4, 2014 · 4 min read

This was originally written on December 2, 2014 and published on Hatch, our internal version of Medium. Read more posts published on Hatch at Inside Medium.


I just finished reading The Life-Changing Magic of Tidying Up and it stirred up all my code deletion happy feelings. If you haven’t read that book, I’m just channeling my inner Marie Kondo.

Despite frequent refactorings, and carefully considered design changes, you may one day look at your codebase and realize that it has a lot of clutter. Do you really need that function? Those new routes you hooked up a few months back haven’t been used at all — do they even still work? Before refactoring portions of your codebase, always consider deleting code first. Delete first, then refactor what’s left.

When you delete code, don’t say “Why was this even here?” or “This code was terrible, I’m glad it’s gone now.” Thank your code for the job it’s done. Take a careful look at it, and express gratitude for the role it has played. Maybe it was never used and was part of a system that was never launched. You can thank it for helping you think through a problem, and for helping you realize that you didn’t need it after all. Or maybe it was an in-between solution that let you launch something more quickly. Thank the code for its important role in letting you ship your feature, and let it go. Code deletion should be a celebration.

Here are some situations in which you may want to delete code.

After a launch

During implementation of a feature or project, while you have the most context, leave handy notes for yourself to make your life easier later.

TODO (yourname): Remove after <whatever> launches

After a feature or project launch, follow these steps:

  1. Make sure you have tests for the new flows.
  2. Remove the launch variants from the codebase carefully, making sure to delete all code attached to the old code paths. It’s better to do this now, otherwise you end up with dangling unused code which is much harder to find later. We can call them danglers.
  3. Also check for any instances of “TODO (yourname): Remove” to find straggling code.
  4. Don’t forget to update or delete the old tests!
  5. Wait until that change is live in production, and then remove the launch variants from deployment-config.

You feel like it

Not all deletable code will be tied to a big product launch. Sometimes a system will be built in anticipation of something we need, but we do not in fact need it yet. Or sometimes code gets deprecated because for whatever reason, it stops being used. If you look for it, you will find that unused code is everywhere!

Start at your routes file and look for completely unused routes. Maybe they were left over from four major releases ago, or maybe someone set it up “just in case.” A quick git-blame will give you what you need to ask for some context and make sure it’s safe to delete.

You can also search for unused graph nodes, though the refactor tool doesn’t handle Bolts very well.

Another approach is to start from the deployment-config repo and look through the flags file. Keep an eye out for things that look like they are probably not relevant anymore, and search medium2 for that flag to find its usages. For flags that have been turned on completely through variants for a long period of time, it’s probably safe to remove them. If they are meant to stay around, the flag description should have a note about its usage. Again, git blame the code to help confirm that they can be deleted. Always delete usages in medium2 and wait for it to reach production before deleting the flags and variants.


With these techniques, you will start to love to delete code. You will feel better about your work and your self. People who have deleted large amounts of code frequently have reported feeling lighter, and have even been seen cleaning off their desk surfaces. Some engineers have reported feeling healthier and losing weight. Others have found it extremely calming and therapeutic.

When you have less code in your codebase, you can truly appreciate the code you do have, and improvements to the codebase become much clearer. Your codebase works hard for you everyday — with unused code gone, it will finally be able to breathe. And with the fresh and clean air, it may speak to you and tell you how it wants to be refactored. Deleting code can help refine your sense of architecture and improvements to existing systems. Take a moment at your keyboard before you begin and end your workday to greet your codebase and thank it for its hard work.

Jean Hsu

Written by

Jean Hsu

Co-founder of coleadership.com, transforming engineers into leaders. Previously engineering at @Medium, Pulse, and Google.

More From Medium

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade