The Life Changing Magic of Tidying Up Your Codebase

This Spring at CodeHS, the engineering team spent the first few weeks of Q2 entirely focused on code cleanup. We called it “Spring Cleaning” and we removed a lot of code we no longer use and tackled quite a bit of technical debt.

Around this time, I also read The Life Changing Magic of Tidying Up by Marie Kondo. She describes the “KonMari” method she invented for managing clutter, keeping your home clean, and sparking joy in your life based on your physical space.

While I didn’t identify with everything she discussed in the book, I found it a few thought provoking comparisons to code cleanup. I took a few ideas from her book to think through why we needed to do a team “Spring Cleaning” and how to go about it.

1. A messy room equals a messy mind”

I also think that a messy codebase equals a messy mind. Especially as your codebase grows and your team grows, having a messy, tangled codebase can be a huge burden on your thought process and work. This Spring, we were a team of 5 engineers working on a codebase that had been around for 5 years and been worked on by over 20 engineers at some point. We were about to have 3 more interns and two full time engineers start over the next few months.

Because of this, it was a really good opportunity to spend some time tidying up and help create an environment that would be less messy for the new people joining to get them off to a good start.

When onboarding a new programmer to a codebase, it never feels good to look at a piece of code and explain that you don’t really use that anymore all the time. It makes it harder for new programmers to trust what’s written to be a good example of how they can make extensions or work in similar areas. It’s so much better to be able to stand by everything in your codebase as a good example of how to work going forward.

2. Tidy all at once

One of the points Kondo stresses in her method is to tidy everything at once and fully focus on the task of tidying. She talks about the idea of “rebound” occurring when you try to break up tidying over a longer period of time.

While we didn’t tidy our entire codebase, we did focus every engineer on the task of cleaning up the codebase and halted all other projects. This made it easier for everyone to prioritize and work together.

The three week long spring cleaning created a time to focus on tidying and tackling a lot of technical debt. We were able to more effectively clean things that we just wouldn’t have gotten to if we tried to tidy as we go normally.

3. Discard before you place things back

Marie Kondo talks about one of the most important parts of her method being that you must discard before organizing. It makes it much harder on yourself to organize before discarding or even while discarding, especially because you’re in a state of flux and will likely need to redo a lot of work.

When we did our spring cleaning, we took a similar approach. While there are a lot of code cleanup and refactoring projects we could have done, we chose to start with discarding code we no longer needed.

We started by removing old views, old urls, old scripts, and parts of the codebase we no longer use. We had a number of deprecated fields on models we had neglected to remove from the database that we didn’t need anymore, so we removed those.

Our initial goal was a challenge to see which engineer could remove the most lines of code. This was both helpful and therapeutic. It’s actually quite fun removing code that was written many years ago and not used anymore.

4. “Someday” never comes

Kondo says that one of the biggest objections she hears against discarding something is that the person could use it someday. However, she argues that the past is the best indicator of the future in these cases and if you haven’t used something for a while, you’re not likely to use it in the future, even if you can imagine a scenario in which you think you would.

The same idea can be applied to code. It can be hard to remove code that you have written. Particularly, it’s difficult if you see code for a feature that never got finished or a feature that currently disabled to be added back later when it’s fixed someday. And it’s especially tempting to think that you’ll save time later when you do get back to it because you won’t have to redo work you’ve already done.

It’s important to really consider that unless it’s actively being used or developed on, code that you may get back to someday is not likely to become useful. Even if the code is a start towards something you eventually work on, it’s likely that by that time, so much has changed that you’ll need to rewrite it anyways. You can make your codebase cleaner and easier to deal with if you just remove that code and move on.

And lastly, it should be even easier to discard code than with physical items. If you’re using version control, the code you remove will always be accessible if you want to find it again for reference, allowing you to breathe easy in case it does become really important to have the code again.

5. Tidy in the right order

Kondo is very particular about tidying your living space in a specific order: Clothes, Books, Papers, and then Komono (miscellaneous). She goes into great detail for how to follow the order correctly and why it’s important. The same idea of going in order can also apply to cleaning a codebase.

I don’t know if there’s one best order for cleaning a codebase, and it may depend on the type of codebase you have, what languages or frameworks you use, or what your goals are. But no matter what specific order is right for you, it’s helpful to define an order. This puts your whole team on the same page and makes it clear how to approach the cleanup.

One trend I saw in the order Kondo chose for tidying is to make the easy decisions first and the hard ones later. The same applies to code. There are many easy things to remove — packages you don’t use anywhere, old pages on your site that aren’t linked to, etc. Start with the things that have the lease emotional investment. Programmers are very opinionated about code, so trying to make progress first on things everyone can agree upon will set you up to succeed.

Only once you’ve cleaned up the easy parts of the code should you start to tackle the harder parts . If you start a code cleanup sprint without defining the order, you’re bound to have someone dive into a difficult, divisive refactor that will end up stalling out and creating arguments about how to best do it. It’s better to gain momentum by cleaning up easy things. You’ll feel like you’ve made lots of progress by the time you get to the more difficult areas that require more discussion.

I hope these ideas can help others think through a code cleanup project and inspire you to take the leap. It ended up being a fun, therapeutic exercise that made our engineers happier with the quality of our codebase.


CodeHS is a comprehensive teaching platform for helping schools teach computer science. We provide web-based curriculum, teacher tools and resources, and professional development.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s