I originally posted this on Twitter. Thought I’d update it and turn it into an article.

I recently spent a couple of weeks refactoring a large chunk of an API we use at work to integrate our software with third-parties. All in all, it was 17 changesets, most of which were refactoring the code to make it easier to switch.

I really enjoyed this work, and I wanted to share how I know what to refactor.

We’re introducing a new (Scala) API (“v2”) to replace an old one (“v1”). For a while, we’ll need both functioning in parallel.

So the plan is:

1. Add (unstable) interfaces for the v2 API.
2. Create adapters back to v1.
3. Port internal code to use v2. Use adapters.

We added the new API and introduce some adapters. So far so good. Next, I had to migrate internal code to the new API. So I start by changing the code. Something breaks. So I change that too, committing with each step. The next thing breaks. And so on.

Eventually, I get to something that isn’t a 1-to-1 mapping, so I can’t just switch it over. I need to make some larger changes.

At this point, I commit what I have so far, and go back to the main branch. (Or sometimes I stash.)

Next, I go to that “problem area”, the thing I needed to change. And I start refactoring. The goal here is to make the switch easy. So typically, it’s either:

1. Identifying similar things and creating more adapters, or
2. Sharing code a little more.

Once I’ve cleaned that up, I commit it to a new branch, rebase my old one onto it, and verify it helped. Switch, improve, commit, rebase.

If it did, I open a PR with just that change. I get it merged, and then continue. And repeat. If not, I keep working on it. Sometimes I’ll scrap the work and try again, if it feels like the change has become too big. Or I start to recurse; switching to a new branch and doing something smaller. (I highly recommend not going more than two levels deep, for your own sanity.)

This process also helps in making sure that code is fully covered with tests. Because I’m working in a small area, it’s usually not a problem to add another test case. I’m not trying to improve coverage across the entire codebase, just the small area that I need to tweak.

Once those changes are merged in, I can make some more progress, until I hit another large change. So I repeat the process. Switch, improve, commit, rebase.

By doing this, I keep the changes small and focused. I also force myself to implement on the old code, which I know works.

Refactoring is tough for a few reasons. It touches a lot of code, you can break things easily, it’s hard to know how much to do, and it’s often not clear if you’ve actually improved anything. By refactoring blockers, you can keep it to just the changes you need. Switch, improve, commit, rebase.

Here’s my rule. If it takes me more than a few minutes (let’s say 15, but less is better) to make the change, I stop what I’m doing, and ask myself: “can I do a smaller thing”?

The answer is pretty much always yes.

Baby steps are often faster than a sprint, if they help you decide the direction.

If you asked me the one thing you could change to improve your code, I’d tell you you’re asking the wrong question.

If you came to me and asked me how to improve the productivity, happiness, and knowledge of your software developers, I’d tell you that I don’t know. But I do know how you can find out.

Introduce pair programming, with frequent rotation. Pairing has a number of benefits that any XP fan (like me) will happily go into, such as getting very fast feedback on your work, keeping each other motivated, and learning how any part of the system works very quickly. I think an even more important benefit that doesn’t get talked about enough is that pair programming is a culture accelerator.

In a team (or company) larger than 5 people, 1 person can’t change much. However, a pair of people that agree on something can talk to others. With pair rotation, those 2 quickly become 4, then 8, and good ideas spread to the point where everyone agrees within days, without calling a meeting or needing a particular person to be some kind of champion for a cause.

Pairing, with rotation, means that a good idea in one person’s brain quickly spreads to everyone’s. When you’re pairing, you don’t complain about something, you improve it. That includes your company culture.

Don’t try and improve your developers' productivity. Make them do it themselves.

Booleans can be confusing.

Hold up. `diff` returns true if they're identifical?

😭 pic.twitter.com/6bmOInnKMz

— David Flanagan (@rawkode) May 11, 2021

Now, let’s first establish that we’re glad the file_diff crate exists and we appreciate the maintainers for their time. This is not an accusation or criticism of their work, simply an exercise in imagining a different universe where the API of diff is different.

So, with that in mind, let’s imagine we are reading some code that uses diff, and we are confused, just as David was. There are a couple of ways we could improve this situation for comprehensibility.

For example, we could change the logic so it returns true when the inputs are different (as implied by the name). That’d work, but then it’d have different behaviour to the diff or git diff programs, which exit with the code 0 (success) when the input files are identical.

Or we could rename the method is_identical (suggested by Stéphane Bjørne). This would make the return value more meaningful, as we can infer from the name what true means.

I’d prefer not to use true and false at all.

Semantically, what are booleans, anyway?

This might seem like a strange question. Truth and falsity, as concepts, are pretty ingrained in us. It’s not just computer people that use boolean logic all the time.

if (it's raining) {
  I pick up an umbrella on the way out ☔️
}

if (it's morning || (I'm tired && not (it's bedtime))) {
  I make coffee ☕
} else {
  I grumble about not having had enough coffee 😫
}

These two examples give us a lot of information about what a boolean is, in terms of what we can do with it. We can “and” (&&) them, “or” (||) them, and not them. (And other stuff, too.) But more importantly, we can if them. We can decide to do something if a boolean is true, and to do something else (or nothing) if the boolean is false.

I like to keep even traditionally system-level dependencies isolated and pinned per-project, so I use Nix for that.

I have been playing with Agda for a while now, and it has been a joy to work with a theorem proof assistant for the first time. (I am hoping to write some more on the topic when I am more familiar with it, but for now, I’ll just recommend Wadler, Kokke, and Siek’s excellent and free book, Programming Language Foundations in Agda.)

I found it a bit of a pain to configure Agda with Nix, and I haven’t found this advice anywhere else, so I thought I’d document it so someone else searching for the same thing doesn’t struggle quite so much.

I am assuming, for the sake of this guide, that you are using Agda with Emacs, which is the only real way to use it due to its heavy editor integration.

So, follow along to set up this combination of incredibly niche tools that you almost certainly have zero interest in. 😜

I got some praise yesterday. A colleague of mine told me that I never shy away from the hard problems.

It’s hard not to have a big grin on your face when you hear something like that.

Got me thinking though… what’s hard, exactly? And so I’ve been musing. Aren’t all problems hard?

Say a customer reports a bug, and you’ve got to fix it. You can fix it. You know you can fix it. Maybe it’ll take an hour, maybe it’ll take a day, maybe a week. But you’ll narrow it down, figure out the smallest possible increment of work you can do to remedy the problem, and then you’ll do it. And as much as it pains me to say it, because I want to be able to check that box that said I did the thing… this is the easy part.

Once in a while, when we’re feeling brave, we also try to tackle the hard problem. We try to answer the questions that we usually avoid.

• Why was this bug caused in the first place?
• Did we know about it before the customer hit it, and if so, why didn’t we do anything about it?
• Was the customer upset? Did we make sure they’re happy again?
• Can we fix not just this bug, but all classes of this bug in the future?
• What are the root causes ingrained in our culture that made this bug possible?
• Can we change our culture to ensure this doesn’t happen again?

These are the hard problems. We can’t always solve them. Maybe they’re too entrenched, maybe you don’t have the power, maybe others don’t see the problem, maybe they’re too expensive to fix. Or maybe you just don’t have the energy to fight this battle. We can’t fight all of them, after all. That way lies burnout.

But every so often, we tackle a hard problem, and we make just a little bit of progress. And whether we do, or we don’t, I think the fact that we sat up, took notice, and recognised that there’s a hard problem here—that’s cause for celebration.