The Life-Changing Magic of Tidy Code — Applying KonMari method to code
After watching a couple of episodes of Marie Kondo’s show on Netflix I picked up her book ‘The Life-Changing Manga of Tidying Up’ as I’ve always been into organisational techniques and the work she did with the people on that show really struck a chord with me.
As someone who works at a consultancy my day-to-day job is dealing with legacy code and tidying it up for the client so it’s easier to work with and is more maintainable in the future.
The KonMari method takes things a step further by bringing sentiment into the process and I think that’s something that’s easy to overlook when refactoring code.
Now I’m not suggesting that developers say ‘thank you’ to every line they delete as refactor code but I think there’s something we can learn from taking the time to understand the value the code delivered instead of just saying ‘which fucktard wrote this!’.
The KonMari Method
Marie Kondo’s manga tells a story of a young professional who is tired of coming home to a messy flat, guys she brings back to her flat calling her messy and how through the KonMari method she is able to realise her dream home through de-cluttering and organisation.
I’ve selected a few of the steps from that process I think could be applied to a codebase to make it easier to work with and ensure it ‘sparks joy’ for the team working on it.
Decide to tidy up
In the book the protagonist realises she has a cluttered home that isn’t working for her anymore and decides to take the step towards improving her situation.
This is actually the hardest step.
There’s a lot of time investment and pride in a code base and it can sometimes be hard to take a step back and realise that the code base is cluttered and needs a good clean.
Additionally refactoring, especially on a grand scale requires time and resources which ultimately will lead to having to get buy in from stakeholders.
Once the right people are onboard the last step is to get in the mindset for tidying up so that the initial job is done well, but also that going forward that it’s easy to see when things are getting cluttered again and things can be corrected before they get out of hand again.
Visualise your ideal lifestyle
This stage builds on the last and helps to create a goal that aids the tidying up effort.
In the book the protagonist does a bit of soul searching and comes to recognise that a lot of her life revolves around her not having enough time to cook and she wants her home to be a place where she can do that.
It can seem a bit hard to apply such a sentimental notion to a code base but I think there’s actually a number of things developers could have a think about in this stage:
- What does the ideal act of writing code look like?
- What does the ideal debugging process look like?
- What does the ideal unit testing process look like?
- What does the ideal integration testing process look like?
- If the code was to be open-sourced with 1000 active contributors, what would the ideal development process look like?
- If the tech world was to suddenly change overnight, what would the ideal porting experience to the new tech be like?
For example a ideal lifestyle for code might be:
- I do TDD properly by writing tests, making them pass and then refactoring when needed
- I can debug the code easily as there’s a clear modular structure to the code and there’s adequate logging in place to aid in finding where things went wrong
- Developers are able to run a subset of the unit & integration tests locally for only the code they changed with a full suite of testing happening on CI to catch regressions
- If the code was open sourced we’d have clear coding guidelines that would be followed to ensure that contributed code was written with the same care as we write ourselves
- We’d be able to port the code to the new technology thanks to a clear separation of concerns for modules dealing with external entities
Once there’s a clear vision this makes it easier to do the next steps as if there’s a tough decision to make you can always ask — does it help me create that lifestyle?
Finish discarding first
This stage is probably the one most people who have heard of Marie Kondo know, it’s the ‘does it spark joy?’ stage.
In the book and the TV show this is where people go through everything in their house and decide what ‘sparks joy’ and what doesn’t, anything that doesn’t spark joy becomes a candidate to be chucked.
Marie Kondo categorises the value we get from objects as such:
- Functional — It serves a functional purpose such as a tattered old sweater
- Informational — It has information we might need such as a book used to learn a language
- Emotional — It has sentimental significance such as an item from a dead relative
- ‘The element of rarity’ — How easy is it to replace the item, is it mass produced or a one off?
Of course when we apply these categories to a codebase pretty much everything would fall under the functional category but it’s important to remember the main goal of the discarding stage is not to throw things away but to identify what ‘sparks joy’.
It’ll be fairly obvious which parts of the codebase don’t ‘spark joy’ as these will be those areas that people hate to work in and are constantly struggling from quality issues.
But how can code ‘spark joy’?
There may be areas of the codebase that are fun to work on from a technical perspective (such as an algorithm that solves a really complex problem) or areas that are very well scoped, well documented and well tested so are a joy to work on.
It’s important during this stage to not get too bogged down with assessing the code’s functional, informational, emotional or rarity value.
Non-joy-sparking-code that’s ‘rare’ may only be rare because of the language it was implemented in and it could be easier to build an adaptor over an existing implementation in another language than to cling onto your code.
Code that is ‘functional’ but doesn’t ‘spark joy’ can be rewritten or you can use a library that offers similar functionality. As long as the behaviour the user expects doesn’t change then it can be discarded.
Code that is ‘informational’ such as documentation should be evaluated on the basis of its code and its compiled form, if the comments on the functions are of no use to a developer but the compiled documentation is really useful then look at tools that allow that informational value to be realised nearer the code.
Test data falls into the ‘informational’ category but most likely doesn’t ‘spark joy’ to developers, abstracting the data out into a library will help declutter to code base while still allowing tests to run.
Code that has ‘emotional’ value seems like a weird concept to me but I guess it might be code that a developer is particularly proud of but it’s important to evaluate that code on it’s currently ability to ‘spark joy’ and not if it did in the past.
Tidy by category
A great technique that the KonMari method uses is to categorise the person’s belongings and then remove the items that fall into that category from their existing context and evaluate all items together.
Marie Kondo describes this as ‘waking up the item after being in storage’ and this really helps, because it gives you fresh eyes on something you may not have looked at in years.
The book makes a really good point about the importance of tidying by category instead of location, as tidying by location is harder due to there being many locations to cover with many categories at each location.
This point rings very true when you’re dealing with a codebase built up over many years, especially where duplication is rampant.
The categories in the book are:
- Clothes — Mostly ‘functional’ value belongings
- Books — Mostly ‘informational’ value belongings
- Papers and Komono — Mostly ‘emotional’ value belongings
While in the book and TV show it’s relatively easy for Marie Kondo’s clients to create massive piles on the floor for these categories but it can be hard to think of an analogy for a similar exercise with code, you can’t sort through a pile of 1,000,000 lines of code on the floor.
The ultimate aim of tidying by category is to assess the ability to ‘spark joy’ in the context of other similar items.
Unlike tidying a house though you can’t just chuck things away as you might end up chucking something that breaks important functionality but you can find another place for that code to live that means the main codebase ‘sparks joy’.
Before throwing away items Marie Kondo thanks them for their service, this is to make separation easier but I think doing so to code will also allow you to appreciate the value that code delivered.
Functionally valuable code
For functional code you can however look at what that code represents.
Assuming there’s a clear set of user stories and user journeys you could look at each module, class and method/function that is called as part of that behavioural grouping and assess its ability to ‘spark joy’.
If you don’t have that information to tie the code to the user’s need then you could assess the code’s ability to ‘spark joy’ based on functional groupings such as code to handle user data, code to talk to external systems.
The main goal of this stage is to find things that don’t ‘spark joy’ in those behavioural or functional groupings that we can get rid of and replace.
Informationally valuable code
For informational code such as documentation and test data you can apply the same logic that Marie Kondo has her clients apply.
In the book the protagonist has many books that she ‘intends to read someday’ and I think this is very true of informational code such as documentation.
If the documentation is purely aimed at external developers and not the application’s internal development team then it doesn’t belong in the codebase.
It pains me to say this but if the development teams ‘ideal lifestyle’ does not involve TDD and the current test suites do not ‘spark joy’ then these too should be removed.
It might be that you end up with a number of smaller projects that come from this stage which pull in the main codebase for their purposes.
This way you still get the benefit of what that informational code brings but it’s removed from the codebase, allowing the development team to live their ‘ideal lifestyle’.
Komono stands for ‘small thing/accessory’, in code this can be things like build scripts, files used for running the application on various platforms (CI, Docker etc).
If these komono don’t serve the ‘ideal lifestyle’ they should also be moved into separate projects or if this isn’t viable then they should be grouped in a subfolder.
Store things where they belong
The KonMari method says to store objects from the same category in one place (clothes all together, books all together etc).
In a codebase things aren’t so clear cut, docstrings for a class will need to be in the same file (and usually directly above) the function they apply to.
However I think if we disregard the functional, informational and emotional categorisation and instead focus on the behavioural and functional groupings used earlier then this just becomes an analogy for separation of concerns.
Real life begins after putting your house in order
In the book this chapter shows how after tidying up and creating a living space that allows the protagonist to live her ‘ideal lifestyle’ things take a turn for the better and she suddenly falls in love with a guy that originally thought she was messy.
I am by no means saying that creating a clean code base will result in a developer magically falling in love!
I do think though that having tidied up the code base that developers may fall in love with coding again and the product will take on a new life as the development team now find it easier to work with the code.
The KonMari method will probably make most developers shout ‘wait, this is just divide & conquer mixed with separation of concerns’ but I think there are a number of concepts in the KonMari method that developers could learn from:
- Visualising an ideal lifestyle — It’s easy to refactor code from a functional perspective but a lot harder to refactor it to make the developer experience more enjoyable
- Waking up dormant items by tidying by category not location — Sometimes it’s easy to overlook the need to revisit old code that could be refactored, moved into better fitted modules or even just deleted in favour of using another implementation
- Saying thank you — It’s very easy to view code as just simply a tool to meet a higher means and for collaborative processes like code reviews to work we can’t be too defensive of the code we’ve written but I think sometimes as we refactor a codebase we should take time to appreciate the value the code delivered as we remove it
The most important tool we could learn though is to ask ourselves ‘does this code spark joy?’
It’s easy to just put up with terrible code because there’s no time allowed to refactor it but sometimes we just need to say ‘this code doesn’t spark joy’ and start the conversation about making the code more joyful to work on.