The reason written next to the code
A comment explained why one database read had to wait for another. The line above it already did the thing the comment said it was protecting against. A reason is a claim, and it deserves the same scrutiny as a finding.
This one is small and we are writing it up anyway, because the shape of the mistake is more useful than the fix.
One of our screens reads a venue, then reads which company owns that venue, then reads everything else in a single batch. The second read had a comment on it explaining why it stayed on its own instead of joining the batch. Roughly: the batch reads the venue’s data, and this read is the question of whether the caller is allowed to have it — so it goes first, separately.
That is a good principle. It is also not what the code did. The line directly above had already read the whole venue row, opening hours and all, before any check ran. The principle the comment named had been broken one line earlier, and the ordering it justified bought nothing at all.
Why it survived
Because it reads well. Somebody scanning that file sees a considered explanation next to a slightly awkward piece of code and moves on — that is what a good comment is supposed to do. The failure mode of a wrong comment is not confusion, it is confidence.
We have now been caught by this enough times to have a rule: a reason is a claim, and it gets held to the same standard as a finding. When we audited a list of eleven such explanations in our own codebase earlier this month, nine held up and two did not — and both of the wrong ones were excusing something from being looked at, which is precisely what a wrong reason is for.
The fix, and what we did not do
The two reads are now asked together. They were always keyed on the same number from the same URL; waiting was the only thing making them sequential.
We also found, and deliberately did not act on, something bigger: the gate in front of every request has already worked out the company that owns that venue, and the screen then asks for it again. Two parts of the system doing the same lookup because neither knows about the other. Removing it means changing what every screen is handed, and that is not a change to make at four in the morning on the strength of one screen. It is written down instead.
And the part we cannot explain
Being straight about this: our arithmetic does not close. We can account for roughly a quarter of the time this screen spends before it starts work. The rest — whatever it is — we have not identified, and putting a plausible name to it would be exactly the mistake this post is about.
If you take one thing from this into your own venue: when somebody explains why a thing is the way it is, the explanation and the thing are two separate claims. Both can be checked. Quite often only one of them is true.