Notes on Reading Code Aloud

I started reading diffs aloud during the pandemic, mostly to stay awake. It turned out to be the highest-leverage review habit I have. The mouth is less forgiving than the eye. The eye will skip a name it has seen two hundred times. The mouth has to say it.

You do not need an audience. You need the sentence. “This function gets the user, unless the user is missing, in which case it gets the user from the session, unless the session is missing, in which case it throws, except in tests.” If you have to take a breath in the middle, the code needs a name or a split.

What turns up

• Boolean soup. If you cannot say the condition without a footnote, the condition is the bug.
• Cowardly names. `data`, `info`, `manager`, `helper` — words you mumble.
• Hidden time. “Then we wait, then we try again” is a state machine pretending to be a script.
• Apologies. Comments that start with “for now” are speaking the truth the code will not.

I do this with agent patches too. The loop cannot hear itself. If I cannot narrate the change in one minute, I do not merge it, even if the tests are green. Green tests mean the cases we remembered. A spoken sentence means I understand the cases we will forget.