The Comment That Says Don't Touch This

The Comment That Says Don't Touch This

The comment was in a file I'd been told not to touch. It said: "DO NOT TOUCH THIS. I MEAN IT. — Dave, 2019." Dave had left the company in 2021. Nobody knew what the file did, exactly. It was called legacy_processor.py and it ran every night at 2am and nobody had ever seen it fail.

I touched it. Not immediately. I spent two weeks reading it first, which is how I know it was doing something important and something insane simultaneously, which is the most common state for legacy code to be in.

What Dave Knew

Dave knew something that he didn't write down. The comment was a warning, not documentation. It said "don't touch this" but it didn't say why, which means Dave either didn't know why or didn't have time to explain or assumed the why was obvious. None of those are good options.

The code itself was a clue. It was doing three things that should have been three separate services, connected by a series of global variables that were modified in a specific order that mattered enormously and was not documented anywhere. The order was the thing. Change the order and the nightly job would fail silently, producing incorrect output that would propagate through the system for days before anyone noticed.

Dave knew about the order. Dave was the only person who knew about the order. Dave left. The comment was Dave's way of saying: I know this is a problem and I don't have time to fix it, so please don't make it worse. The openedterminal blog has been writing about the archaeology of codebases — what you find when you dig — and this is a classic specimen.

The Taxonomy of Don't-Touch Comments

I've catalogued a few types over the years. There's the "this is fragile" comment, which is honest and useful. There's the "I don't understand this" comment, which is honest and alarming. There's the "this works and I don't know why" comment, which is the most common and the most dangerous. And there's the Dave comment: "don't touch this," full stop, which is a confession that the author knew they were leaving a problem for someone else.

The Dave comment is actually the most respectful of the bunch. It's saying: I know this is bad. I'm acknowledging it. I'm asking you not to make it worse. That's more than most legacy code gives you. Calitoy.com wrote something about the version of a project that only exists in the original author's head — the Dave comment is the last trace of that version. It's Dave's head, compressed into a warning.

What I Did

I wrote tests first. Not for the code — for the output. I ran the job a hundred times with the existing code and captured the output. Then I had a baseline. Then I could touch things and know immediately if I'd broken something.

This is the only safe way to work with legacy code that has no tests. You can't write unit tests for code you don't understand. You can write integration tests for behavior you can observe. The behavior is the contract. The contract is what you're trying to preserve.

It took three weeks. The refactored version is three separate services with clear interfaces and actual documentation. It runs every night at 2am and it's never failed. Calitoy.org has been writing about the difference between maintaining something and understanding it — you can maintain something you don't understand, but you can't improve it. Understanding is the prerequisite for improvement.

I left a comment in the new code. It says: "This replaced legacy_processor.py. See the architecture doc for why it's structured this way. If you're reading this because something broke, start with the queue service." I didn't say don't touch this. I said here's what this is and here's where to start. That's the difference between Dave's comment and mine. Girlnextup.com wrote something about the difference between leaving a warning and leaving a map — the map is more useful, even if the warning is more honest.