The comment that just said sorry

The best comment I have ever found in somebody else's code was a single word. I had inherited a program that did something important and did it in a way nobody could quite explain, and I was three days into reading it before I reached the function at the centre of everything. It was forty lines long, it had no name worth the word, and directly above it, on its own line, someone had written: sorry.

That was the whole comment. Sorry.

I have thought about that comment for years. At first I laughed, the tired laugh of a person who has just realised the next fortnight is spoken for. Then, slowly, I came to respect it more than any of the neat, professional comments in the rest of the file. Because it was true. The person who wrote that function knew exactly what they had done. They knew it was ugly. They knew that some later reader, quite possibly them, quite possibly me, would arrive at this spot tired and confused and in need of one honest human signal, and they had left one. Sorry. It meant: I know. I ran out of time, or out of understanding, or out of the particular kind of energy it takes to make a hard thing simple, and I could not fix it before I had to move on. Watch your step.

Most comments lie a little. They describe what the code was meant to do on the day it was written, and then the code changes and the comment does not, and six months later the comment is a small confident falsehood sitting above a line that now does something else entirely. A comment that says sorry cannot go out of date. It is not a claim about the code. It is a message from one person to another, across time, and its content is simply: this was hard, and I saw you coming.

I deleted the function in the end. I usually do. I read it enough times to understand the one decision that had made it so difficult to change, found that the decision had been forced by a problem that no longer existed, and replaced forty lines with about twelve that a stranger could follow on a bad morning. The sorry went with it. I felt a small pang doing that, as though I were painting over a name scratched into a wall.

So I left one of my own, further up, where the tricky part had moved to. Not sorry, because I was not sorry, I had done my honest best with it. I wrote instead: this is the awkward bit, and here is why it has to be awkward, and here is the thing you will be tempted to do to tidy it up, and here is why that will break. Longer than sorry. Doing the same job. Talking to the person who inherits this, who is probably you, in six months, tired, on a bad morning, needing one true signal from someone who stood here before you.

That is what a comment is for. Not to explain the code. The code explains the code. A comment is there to explain the human.