A practical, no-fluff guide to debugging real software problems. Every technique here comes from real production incidents — not textbook theory.
"Debugging is twice as hard as writing the code in the first place." — Brian Kernighan
Most debugging guides teach you how to use a debugger. This one teaches you how to think when things break. Whether it's a 3 AM production outage or a bug that only appears on Tuesdays, the mental models here will help you find the root cause faster.
| # | Chapter | What You'll Learn |
|---|---|---|
| 1 | The Debugging Mindset | How to approach bugs systematically instead of guessing |
| 2 | Reproducing Bugs | The most critical (and most skipped) step |
| 3 | Binary Search Debugging | Halving your search space to find bugs in minutes |
| 4 | Reading Error Messages | What error messages actually tell you (and what they hide) |
| 5 | Logging That Actually Helps | Structured logging, correlation IDs, and log levels done right |
| 6 | Debugging Production Issues | Safe techniques when you can't attach a debugger |
| 7 | Memory Leaks & Performance | Finding leaks, profiling hotspots, and reading flame graphs |
| 8 | Debugging Distributed Systems | Tracing requests across services, race conditions, network failures |
| 9 | Common Bug Patterns | Off-by-one, null references, race conditions, and 20+ more |
| Cheatsheet | Description |
|---|---|
| Debugging Checklist | Step-by-step checklist for any bug |
| Language-Specific Tips | Python, JavaScript, Java, Go — common gotchas per language |
| Tool Cheatsheet | Quick reference for gdb, strace, tcpdump, Chrome DevTools, etc. |
Real buggy code with walkthroughs showing how to find and fix each issue.
examples/
├── python/
│ ├── null_reference_bug.py # The classic NoneType error
│ ├── race_condition.py # Threading bug with shared state
│ ├── memory_leak.py # Subtle leak with growing cache
│ └── silent_exception.py # Bug hidden by bare except
├── javascript/
│ ├── async_debugging.js # Promise chain losing errors
│ ├── closure_trap.js # The infamous loop variable bug
│ └── type_coercion_bug.js # When '1' + 1 = '11'
└── java/
├── concurrent_modification.java # Modifying collections during iteration
└── equals_hashcode_bug.java # Why HashMap "loses" your objects
If you're fighting a bug right now → Start with the Debugging Checklist
If you want to get better at debugging → Read the chapters in order, then try to find the bugs in examples/ without looking at the solutions
If you're preparing for interviews → Chapter 9 (Common Bug Patterns) covers the most frequently asked debugging scenarios
Found a bug pattern that should be here? Have a war story worth sharing? Contributions are welcome!
- Fork this repo
- Add your content (follow the existing chapter format)
- Include a real-world example if possible
- Submit a PR
Please keep examples practical and production-relevant. We're not looking for contrived puzzles — we want the kind of bugs that make senior engineers sweat.
MIT — use this however you want. If it helps you debug faster, that's all that matters.