Clear Thinking

Latest news and opinion from the Clearleft team

Technical debt and refactoring

I’ve been working on the upcoming relaunch of the Clearleft website, complete with a whole new brand identity!

Working on internal projects like this can be quite a challenge. On the one hand, it’s a great opportunity to try out new development techniques and technologies that might not always be appropriate on a client project. On the other hand, the internal projects never feel like they’ve got the same status as client projects. It can be really hard to get people’s time devoted to an internal project when they’ve got client projects they’re working on. It’s inevitable that at a design agency like Clearleft, clients are always going to come first.

Because of the stop-start nature of people’s time on the project (and because they are lots of very invested stakeholders) the development process has been a little challenging. Design changes keep getting made that then require more development work …but without any change to the deadline. I suppose that devs will always feel this crunch (whether it’s on internal or client projects) because the development part of a project is the part closest to the end.

Sometimes I wonder whether an old-fashioned waterfall approach wouldn’t be better, with all the design work done up-front before beginning development. But then, that brings its own problems. If the design is set in stone, then any problems with the design can’t be addressed during development. It makes more sense to have a fluid design and development back and forth. But it can feel frustrating when it seems like things are going around in circles.

But even though this is a challenging process, it’s also a very rewarding one. I think that’s partly because we’ve got a close-knit team working together on this. Jon, Graham and I have taken over a corner of the office and plastered the wall with print-outs of designs in progress. That’s made such a huge difference when it comes to communication—we’re all working with the same knowledge about where the project is going, and what decisions have been made so far.

Something else that really helps communication is that we’re all using the same vocabulary to talk about interface elements. I ran a version of my pattern-naming exercise early on in the project. That resulted in a vocabulary of terms that we not only use when we’re working together, but will ultimately end up as class names in the patterns for the site.

Of course we’re making a pattern library with Fractal. We’ve got to eat our own dogfood, right?

Even on a relatively narrowly-focused project like the Clearleft site, a pattern library is really useful for ongoing maintenance. It can serve as the single source of truth for anyone in the company who needs to change the code in the future.

At the same time, it’s important that the patterns are flexible enough that they can change as the project progresses. This is something I’ve really struggled with: on the one hand, I want to get everything just right, but on the other hand, there’s a pressure to get as much as possible done in a short space of time. I find it hard to just “bash something out”; I keep wanting to craft it to be perfect right from the start. But that just makes the inevitable design changes even more frustrating—I spend all this time getting something as good as it can be, and then it ends up changing anyway.

Something I’ve been trying out to get around this is to allow for a big refactor. Knowing that there’s time set aside to revisit patterns makes it easier for me to create a looser first stab at them. This is something that Harry Roberts wrote about recently. In a way, what I’m doing is creating technical debt for myself. But it’s a very deliberate kind of technical debt. I know that time is set aside later on to revisit the codebase and fix anything I need to. That’s quite liberating.

I think that this kind of built-in refactoring time is a good idea for a pattern library anyway. There have been a few patterns where I thought I knew what was the default style and what was a variant, only to have that assumption change as the design evolved. A refactor gives me the chance to fix those decisions. It’s also a chance to change how the patterns are organised—units, components, groups, and so on. Those terms can be hard to predict in advance.

It sounds strange but accepting technical debt (as long as it comes with a planned refactor) has helped me to resolve the inherent uncertainty on this project. I can treat early versions of patterns as prototypes, knowing that they’ll only become production code after refactoring.

Read the next blog post about the new site and rebrand: Developing our style by Hana Stevenson