Rubber Duck Debugging: Why Explaining Code Finds Bugs
Explaining your code out loud often reveals the bug before you finish. Learn why it works and how to use it deliberately.
By Velloreth
What it is
Rubber duck debugging is explaining your code, line by line, to an inanimate object. The classic object is a rubber duck, but a plant, a wall, or a text file works equally well.
The premise is simple: the act of explaining forces you to examine your assumptions, and the bug often reveals itself before you finish the explanation.
The name comes from The Pragmatic Programmer, where the authors describe carrying a rubber duck and explaining code to it. The technique predates the book — programmers have talked to themselves for as long as there have been programs — but the name made it a recognised practice.
Why it works
The mechanism is about making implicit reasoning explicit.
When you read code, you skim. You see if (user.isActive) and your brain supplies “check if the user is active” without examining whether isActive is what you think it is. You see a loop and assume it iterates the right collection.
When you explain, you must produce a sentence. And producing a sentence requires committing to a claim.
“This line checks whether the user is active.”
Now the claim is explicit, and it can be wrong. You look at isActive and discover it is a function, not a boolean, so if (user.isActive) is always truthy. The bug was invisible while you skimmed and obvious the moment you stated it.
This is why the listener does not need to understand. The value is not in the response; it is in the articulation.
How to do it
1. State the goal. What is this code supposed to do?
“This function should return the total price of all active items in the cart.”
2. Walk through line by line. For each line, say what it does and what you expect.
“This filters the items array, keeping only those where
isActiveis true. So after this line,activeItemsshould contain the two active items.”
3. Check each expectation against reality. This is where the bug appears.
“Wait —
isActiveis a method, not a property. Soitem.isActiveis a function reference, which is always truthy. The filter keeps everything.”
4. Continue until you find the discrepancy. Often you find it at step 3, before finishing.
The critical discipline is step 3. It is not enough to say what the line does; you must verify that it does what you said. The gap between the two is the bug.
The failure mode
The technique fails when you summarise instead of explaining.
“This function processes the order and returns the total.”
That sentence skips every detail where the bug lives. It is a description of intent, not an examination of behaviour.
The other failure mode is explaining what you meant rather than what the code says.
“This checks if the user is active.”
You meant to check if the user is active. The code checks if a function reference is truthy. The difference is the bug, and it is invisible if you explain your intent.
The discipline is to read the code literally and state what it actually does.
Writing instead of talking
Writing the explanation works as well as speaking it, and has two advantages.
It forces complete sentences. You cannot mumble through a gap in writing. The sentence must be finished, and finishing it requires resolving the ambiguity.
It leaves a record. You can refer back to the explanation, and if you do end up asking a colleague, you already have the write-up.
A useful format is a short document:
## What this should do
Return the total price of active items.
## What it does, line by line
1. `items.filter(i => i.isActive)` — keeps items where isActive is truthy.
PROBLEM: isActive is a method, so this is always true.
2. `reduce(...)` — sums price * qty.
## The bug
Line 1 keeps all items because isActive is a method reference.
The act of writing the “PROBLEM” line is the moment of discovery.
Rubber ducking before asking for help
The technique is most valuable as a step before asking a colleague.
The sequence:
- Get stuck.
- Explain the problem to the duck.
- Either solve it, or produce a clear explanation.
- If still stuck, ask a colleague with the explanation ready.
Step 3 is the payoff either way. If you solve it, you saved a colleague’s time. If you do not, you have already done the work of framing the problem, which makes the conversation much shorter.
This is why many teams have a rule: explain the problem in the help channel before asking. The explanation often resolves it, and when it does not, the question is well-formed.
Related techniques
Explain it to a junior developer. A real person who asks “why?” is even better than a duck, because their questions expose assumptions you did not know you had.
Write the bug report first. Describing the bug precisely — steps to reproduce, expected, actual — often reveals the cause.
Draw the flow. Sketching the data flow on paper makes the mismatch between expectation and reality visible.
Read the code aloud. Speaking forces a slower pace than reading, which gives your attention time to catch discrepancies.
Explain the fix before applying it. If you cannot explain why the fix works, you do not understand the bug.
When it does not help
When the bug is not in the code you are reading. Rubber ducking examines your understanding of a specific piece of code. If the bug is in a dependency, a configuration file, or the data, explaining the code will not find it.
When the problem is environmental. A missing environment variable or a version mismatch is not a logic error, and no amount of explanation will reveal it.
When you are too tired. The technique requires attention. At the end of a long day, you will summarise instead of explaining, and it will not work.
When the code is genuinely correct. Sometimes the bug is elsewhere, and you are explaining working code. The technique will confirm the code is fine, which is also useful information.
Practical guidance
- Explain line by line, not in summary.
- State what each line actually does, not what you intended.
- Verify each expectation against the code.
- Write it down if speaking does not work.
- Do it before asking a colleague, so you either solve it or ask a better question.
- Use a real person when available — their questions are more valuable than silence.
- Take a break if you find yourself summarising; fatigue defeats the technique.
For the related techniques, see debugging strategies that work and debugging with breakpoints. For the broader context, incident response for solo developers and technical debt conversation.
Quotable summary
Rubber duck debugging works because articulating a problem forces you to make your reasoning explicit, and implicit assumptions are where bugs hide. The listener does not need to understand the problem; the benefit comes from the act of explaining, not from the response. It is most effective when you explain the code line by line, stating what you expect each line to do and then verifying that it does — the gap between expectation and reality is the bug. Writing the explanation works as well as speaking it and leaves a record. It fails when you summarise instead of explaining, or when you explain what you intended rather than what the code actually says.