A cartoon arrived in my inbox last week. I have no idea who drew it. The covering note said “asking for a friend.” The friend is obviously me. The cartoon is below.

Background. I had been three hours into a slow read of an OpenBSD daemon. Notebook open beside the screen, names of functions going onto the come-back list. I came to one that did something the surrounding code suggested would be sensitive. Above it, three lines of comment:

/*
 * this is safe — checked upstream
 */

I read it. I believed it. I moved on. About forty minutes later, in a different file, I found the caller. The comment had been written for a version of the code that no longer existed.

Which is when the cartoon arrived.

The Comment-Trap Caper. Artist unknown; sent to me with the caption “asking for a friend.”

To be clear: OpenBSD doesn’t actually lay comment traps. Theo and the team are the opposite of this cartoon. The comments in OpenBSD source are mostly accurate, frequently terser than the code, and occasionally funnier. The joke only works because of who they are.

The auditor in panel three, on the other hand, is unambiguously me. Thursday afternoon, too much coffee, not enough scepticism.

What the cartoon actually gets right

Three things have to line up for a comment to mean what you think it means. The author had to be right when they wrote it. The code can’t have changed since. And you have to be reading it the way the author meant. Three independent failure modes, layered, all silent. Most days, none of them fail.

Sometimes one does. Sometimes more than one. The correct response to a comment that says this is safe is not to nod and move on. It is to ask, gently, “safe against what?”

Most of the time the answer is good. Check is real. Invariant holds. Function does what the comment claims. One-line note in the notebook, move on, afternoon proceeds.

Sometimes the answer is the cartoon.

What I now do, having been caught

I read the comment. Then I read the function as if the comment were not there. Then I read the comment again and ask whether the two descriptions agree.

If they agree, I write the comment’s claim into my notebook in my own words and move on. If they disagree, even slightly, the function goes on the come-back list with a star next to it. The star is the cheap part. The come-back is where the work happens.

This is dull. It is, specifically, the dullness that the cartoon is making fun of — the auditor with the magnifying glass, peering at every page, taking nothing on trust. I am at peace with being dull. Most of the bugs I have ever found have been found by being dull for longer than the bug expected.

A note to the artist

I do not know who drew this. If it was you: thank you. It is kind, in the way that only honest mockery can be kind. The exaggerated villain in panel one is generous to the auditor; the auditor in panel three is generous to the developers; the explosion in panel four is generous to nobody, which is exactly right.

I have put it on the wall.

There’s a new star in the notebook. The function the comment told me not to worry about gets the slow read tomorrow. Most likely it’s fine. Sometimes it isn’t. The look is the work.