Writing a Minimal Example
When you're stuck on a bug, one of the most powerful techniques is creating a minimal example — the smallest piece of code that still shows the problem. This process often reveals the bug, and if it doesn't, you'll have something clear to share when asking for help.
What Makes an Example Minimal
A minimal example:
- Reproduces the bug — Running it shows the problem
- Contains only necessary code — Nothing extra
- Is self-contained — Someone else can run it without your full project
- Uses simple data — Hard-coded values instead of complex setup
The goal is distilling your problem to its essence, removing all the noise so the signal is clear.
The Reduction Process
Start with your full code and systematically remove things:
- Copy the relevant section to a new file
- Replace complex inputs with simple hard-coded values
- Remove unrelated functions and imports
- Delete code that doesn't affect the bug
- Test after each removal — does the bug still happen?
If removing something makes the bug disappear, that code is related to the problem. Add it back and try removing something else.
# Original: 200 lines with database connections, API calls, etc.
# Minimal example: 10 lines that show the same bug
def calculate_discount(price, discount_percent):
return price - (price * discount_percent) # Bug: should divide by 100
# Test case that shows the bug
result = calculate_discount(100, 10)
print(result) # Prints -900 instead of 90
Why Minimizing Reveals Bugs
The reduction process forces you to understand what's actually relevant. Often, while removing "unrelated" code, you discover it wasn't unrelated at all — or you realize the bug is simpler than you thought.
Sometimes the minimal example works correctly, which tells you the bug is in the code you removed — the interaction between components, not the core logic.
Minimal Examples for Getting Help
When asking for help (from AI, forums, or colleagues), minimal examples are invaluable:
Hard to help with: "My 500-line program crashes sometimes. Here's all the code..."
Easy to help with: "This 10-line function returns wrong values. Input: [1,2,3], Expected: 6, Actual: 5"
People can quickly understand, run, and debug minimal examples. They're more likely to help, and they'll help faster.
The Rubber Duck Effect
Creating a minimal example often solves the bug before you finish. The act of carefully examining each piece of code, deciding what's relevant, and testing systematically leads to understanding. Many programmers report that they find the bug while preparing to ask for help — the preparation itself was the debugging.
"If you can't explain it simply, you don't understand it well enough." — This applies to bugs too.