The function everyone was afraid to touch

The function was four hundred lines long and it was called doTheThing, which I have changed only slightly to protect the guilty. Above it, in a comment, someone had written: "Do not touch this. It works. We are not sure why."

I inherited it the way you inherit most things in this job, which is to say nobody handed it over and nobody warned me. It simply sat there in the file I needed to change, like a wasps' nest in the loft of a house you have just bought. Everyone on the team knew about it. Everyone routed around it. New features grew in strange shapes specifically to avoid going near it, the way a path in a wood bends around a tree that fell long before anyone walking there was born.

For a week I did nothing but read it. I did not change a character. I wrote down, in plain words on actual paper, what each part seemed to be doing. And slowly the fear drained out of it, because it turned out doTheThing was not doing one terrifying clever thing. It was doing three ordinary things that had been stitched together years ago by someone in a hurry, and then never pulled apart again.

Most code that frightens people is not clever. It is just three simple things wearing one coat.

One part fetched some records. One part reshaped them. One part decided what to send back. They had no business being in the same room, let alone the same function. They shared variables with names like temp and temp2, which is how you know two things that should be strangers have been forced to live together.

So I separated them. Three small functions, each with a name that said what it did, each short enough to read without scrolling. I deleted the comment about not touching it, because the whole purpose of that comment was fear, and there was nothing left to be afraid of. The tests, such as they were, still passed. A few I had to write myself, which told its own story about how the thing had survived so long.

When I was done there was less code than when I started. Noticeably less. I have never once regretted deleting code, and I have regretted keeping it more times than I can count.

Here is the part I actually want the next person to hear. The scary function is almost never scary because it is too advanced for you. It is scary because nobody has taken the time to understand it out loud, on paper, without flinching. The fear is not information. It is just the absence of someone willing to read slowly.

I left a comment above the three new functions. It says what they do. It does not say do not touch this, because the next person, who is probably you in eighteen months, is allowed to touch all of it. That is the job. You read what the last person left, you make it a little smaller and a little clearer, and you leave it better lit for whoever comes after you.

Fewer moving parts make fewer frightening functions, which is much of the case for building the way Nothing But Node does: no frameworks, no magic.