What I always notice reopening old code

There is a specific feeling, familiar to anyone who writes software, of opening a file you wrote a year ago and meeting a stranger who had your job, some of your opinions and none of your current sense. I did it again this week, reaching into an old project for one small fix, and I started keeping a list of what I noticed, because the list is always roughly the same and it is always instructive.

The first thing I notice is that the clever part is the part I cannot read. The line I was proudest of, the one that did three things at once in a single expression, is now a small locked box. I know it works. I no longer know why. The boring, long winded version I almost deleted for being boring is the part I can still follow at a glance.

The second thing is that my past self did not trust my future self, and was right. Wherever I left a comment that simply said what the next line already said, I wasted both our time. But wherever I left a comment explaining why, why this odd order, why this guard, why we do not do the obvious thing here, I could have kissed him. The why is the only comment worth writing.

The third thing is the name I got wrong. There is always one. A variable called data, a function called process, a thing called helper that grew into the most important object in the file and never got renamed to match its promotion. Bad names are not a cosmetic problem. They are the fog you walk through every time you come back.

The fourth thing is that I was afraid of deleting code, and the fear cost me. Commented out blocks, kept just in case, sit there like furniture under sheets in a closed house. They are never needed. They only make the room harder to cross. The history already remembers the old code. I did not have to.

The fifth thing is that the test I resented writing is the reason I can make this fix at all. A year ago it felt like a tax. Today it is the one thing telling me, in under a second, whether the change I just made broke something I have completely forgotten exists. Nothing else in the file is as kind to me as that grumpy little test.

You are not writing for the computer. You are writing for the stranger who has your job next year, and that stranger is tired.

The last thing I notice is harder to put down. The file I am least ashamed of is almost never the cleverest one. It is the plainest. It says what it does, it does one thing, it is a little too long and not at all impressive, and a year later it opens like a well lit room. I keep relearning this and keep forgetting it the moment a clever line is within reach.

So that is the list. I will write something clever again this afternoon, feel wonderful about it, and meet it as a stranger next autumn. The work, as far as I can tell, is mostly leaving yourself a kinder note.

Forgetting is a feature in hardware too: Chips That Forget opens the tiny memory circuit that survives by forgetting and keeps the modern world responsive.