Eliminating Cruft, One Week at a Time

What is Cruft Week?

Overtime, regardless of the team or project, a repository builds up cruft. The definition for cruft from Wikipedia is:

💡 Cruft is a jargon word for anything that is left over, redundant and getting in the way. It is used particularly for defective, superseded, useless, superfluous, or dysfunctional elements in computer software.

It can't be helped - it always shows up. Even as the codebase is (hopefully) delivering better features overtime, there's an inevitable buildup of code that is no longer needed or has fallen out of the prescribed pattern.

This isn't visible to end product users, but it is something that the engineering team sees on a daily basis. Letting small anti-patterns and messes pill up overtime makes it difficult to understand exactly what the code is doing which in turn increases the likelihood of introducing bugs into the application.

And so while we do our best to clean it up as we go, we introduced a cruft week. A cruft week is to address this buildup directly via a dedicated sprint. Outside of the sprint, a running master list of cruft items is collected to form the basis of the work. Tasks are pulled from this master list and assigned just like a normal sprint.

And then we go to work.

What Was Our Cruft?

For us in this initial cruft week, the cruft items were pretty varied.

• Renaming a widely used variable: one thing we did was to rename a variable used extensively in the backend. While the concept of the change was pretty straight forward, it was used everywhere which made the changes pretty significant. We wanted to do this to remove the constant linting warnings we got which could be pretty annoying while reading code.
• Updating package structures: our frontend Redux packages were following mixed patterns and we opted to unify them into a more up-to-date and recommended structure. This was to help with readability and comprehensibility for new developer team members.
• Adjusting package functionality: another change we made was to update one of our backend package to follow our new design paradigm. The older structure was harder to test and less intuitive so moving to a more “functional” paradigm made sense as part of our broader cruft changes.
• Add TypeScript to frontend: notably, we added TypeScript to our frontend packages. This was to take advantage of the “type safe” features that TypeScript offers and to make things more explicit to developers working in those packages.
• Consolidate backend testing approaches: on the backend, we also converted the majority of our tests to use the gomock package instead of hand-rolling our mocked resources. This helps us to more quickly understand our tests and test coverage when scanning the code instead of having to review mock implementations.

Other stuff we didn't get to was adding in tooling or some more comprehensive backend refactoring; admittedly these might be a bit larger than what can be done in a cruft week so we still need to scope them out fully. Collecting these into a master list was very helpful to see what we could reasonably accomplish in a week and what would have to wait until later.

What Did the Week Accomplish?

Tackling this cleanup as a more comprehensive week-long investment allowed us see value more quickly than in a piecemeal fashion over time. Here are a couple of the benefits from taking that approach.

• Remove outdated patterns: moving towards the latest best practices helps keep the code up-to-date and easier to work with. With increasing amounts of the codebase following unified specifications established by the team, there are fewer exceptions to mentally keep track of while working in the repository.
• Reduced cognitive overhead: because there are fewer exceptions to track, cognitive overhead is reduced while reading the code and since code is more often read than written this is a powerful benefit. Additionally, it makes things much easier when new people join the team - both for the person walking them through the codebase and the learning picking things up for the first time.
• Developer pride: the state of the codebase is a reflection of a developer's work and as such they generally take great pride in presenting a clean, intuitive repository to readers. Clearing out weird exceptions or old naming choices bolsters pride and ownership in the work being delivered.

What Will We Do Differently?

Overall, the team was very pleased with the results of our trial cruft week. Going forward, our tentative plan is to do a cruft week every two quarters since we still have a backlog of things we'd like to improve. Nothing on the list is immediately pressing or impacting users, but we'd still like to keep up a steady pace of improving our codebase over time.

Doing this in chunks, while simultaneous addressing small things here and there during regular sprints, is a sort of "spring cleaning" that everyone enjoys getting involved in.