The best thing I wrote last month was the code I deleted

Someone wrote in with a good question, the kind I like because it has no clean answer. How do you know, they asked, when a piece of code should be deleted rather than fixed? They had a function that everyone on their team was afraid of, and they wanted a rule.

I do not have a rule. But I have a feeling I have learned to trust, and I can try to describe it.

The first sign is fear. Not yours, everybody's. When a piece of code has reached the point where no one will change it without a good reason and a deep breath, that fear is information. It usually means the code is holding more in its head than any one person can, and code that has to be understood all at once, or not at all, is code that has stopped helping you. Fear is the smell of something that wants to be smaller.

The second sign is the comment that apologises. You know the one. This is horrible but it works. Do not touch unless you understand X, Y and Z. Every apologetic comment is a small confession that the code and the idea behind it have drifted apart, and that someone patched over the gap with a sentence instead of a rewrite. I read those comments as invitations.

Deleting is not giving up on the code. It is giving up on defending it.

Here is the part people find hard, and it is the actual answer to the question. You cannot know whether code should be deleted until you have understood it well enough to rewrite it, and once you have understood it that well, you almost always can rewrite it smaller. The understanding is the expensive part. The deletion is cheap, and it feels, wrongly, like the risky part, so people avoid doing the cheap safe thing because it looks like the dangerous one.

So my honest method is this. When a piece of code frightens the team, I do not try to fix it in place. I sit down and force myself to explain, in plain words, what it is actually supposed to do, stripped of every clever thing it currently does to achieve that. Nine times out of ten the plain words are much shorter than the code. That gap, between what it does and what it needs to do, is the code you get to delete. Then I write the small version next to the old one, prove they agree, and remove the original without ceremony.

The person who inherits your code, and it is usually you in six months, does not want to admire your cleverness. They want to be able to change one thing without discovering they have changed four. Every line you delete is a line that can never break, never confuse, never need a comment that apologises for it. I have never once regretted making a working program smaller. I have regretted, many times, leaving something in because I was proud of it.

So to the person who wrote in: you do not need to be sure the frightening function should die before you start. You need to understand it well enough to say what it is for in one sentence. If that sentence is much shorter than the function, you have your answer, and it will be one of the more satisfying afternoons you spend all month. Ask me for a favourite language another time. This is the favourite thing.