GitHub & Projects
How to Debug Like a Detective: A Student's System for Finding Bugs Faster
Debugging eats more student coding time than writing new code. A five-step detective system — reproduce, read, narrow, question, change one thing — finds bugs faster.
If you added up all the hours you spend coding as a student, debugging would win by a mile. Writing a new feature feels like progress. Debugging feels like being stuck. But here is the uncomfortable truth I learned the slow way: debugging is most of the job. Professional developers spend a huge part of their day on it too — the difference is not that they write bug-free code, it is that they have a system for finding bugs instead of panicking at them.
My early approach was pure panic. Something broke, so I changed things at random and hoped. Sometimes it worked, and I had no idea why. Sometimes it got worse, and I had no way back because I could not remember what I had changed. The fix that finally helped was embarrassingly simple: I stopped treating a bug as a disaster and started treating it as a mystery with clues. Detectives do not guess. They collect evidence, narrow suspects, and test one theory at a time. That is the whole system below.
Step 1: Reproduce it on demand
Before you touch a single line of code, make the bug happen again — deliberately, and more than once. A bug you can reproduce is a bug you can study. A bug that appears randomly is a ghost story. Write down the exact steps: what you clicked, what you typed, and what happened versus what you expected. If you cannot reproduce it, you do not have a bug report yet. You have a rumor. And while you are at it, save a copy of the working version, or commit your code, so you always have a way back to before you started changing things.
Step 2: Read the error message properly
Most beginners do the same thing with an error message: they panic, skim the red text, and paste the whole thing into a search engine. Slow down and read it first. The first line usually tells you what went wrong. The file name and line number tell you where. The top of the stack trace tells you which of your functions was running when it broke. Nine times out of ten, the answer is sitting right there in words you skipped because you were in a hurry. Search engines are for the tenth time, not the first nine.
Step 3: Narrow the suspects
A bug lives somewhere in your code, but your code might be hundreds of lines long. Do not read all of it hoping the bug jumps out. Cut the search space in half, again and again. Comment out half the feature and see if the bug survives. If it does, the bug is in the half that is still running. If it does not, it is in the half you removed. Print the actual values of your variables at the suspicious points — not what you think they are, what they really are. Half the time, the value is not what you assumed, and the mystery is over.
- Halve the code: disable half the feature, test, and repeat on the guilty half.
- Print real values: log the variable, the API response, the list length — assumptions are the usual culprit.
- Test the smallest case: one item instead of fifty, one user instead of a thousand. Small cases expose the flaw faster.
Step 4: Question your assumptions
Here is a pattern every developer knows: you stare at a function for an hour, convinced it is correct, and the bug is in the line above it that you never doubted. Maybe the data arriving is shaped differently than you expected. Maybe the function runs before the data loads. Maybe you are editing one file while the app runs another copy. The code is usually doing exactly what you told it to do. The mistake is in what you told it — or what you assumed it already knew.
The rubber-duck test
Explain the code out loud, line by line, to an imaginary listener — or a real classmate, or a rubber duck on your desk. The rule is simple: you cannot skip a line, and you cannot say it obviously works. The moment you are forced to justify a line out loud is usually the moment you hear how wrong it is. I have solved more bugs mid-sentence than I have solved by staring at the screen.
Step 5: Change one thing at a time
When you think you have found it, change exactly one thing, then test. If the bug is gone, you know what fixed it. If you change three things at once and the bug disappears, you have learned nothing — and the next time it appears, you will be guessing again. Worse, one of your three changes might have quietly broken something else. Slow is smooth, and smooth is fast. This is the rule beginners resist most, and the one that saves the most time.
Three traps that waste hours
- Blaming the tool first. The framework, the library, the compiler — they are almost never the problem. Your code is. Check your code first, and only suspect the tool after you have proof.
- Pasting a fix you do not understand. A copied answer that makes the error disappear is not a fix, it is a delay. If you cannot explain why it works, it will break again, and you will not know why.
- Debugging for hours without a break. After thirty stuck minutes, your brain stops seeing clearly. Stand up, walk away for ten minutes, and come back. The bug is often obvious on the second look.
When you are stuck, ask a good question
Sometimes you genuinely need help, and that is normal. But saying your code does not work is not a question anyone can answer. A good question has four parts: what you were trying to do, what you expected to happen, what actually happened (with the exact error), and what you have already tried. Write it down before you ask — half the time, writing the question clearly shows you the answer before anyone replies. And when someone does help you, write down the cause and the fix. That note is pure gold the next time the same bug appears.
Debugging is not the opposite of coding. It is coding with the lights on — slower, more careful, and far more honest.
Keep a bug log
The highest-return habit in this whole post is also the simplest: keep a running log of every bug you fix. One line for the symptom, one line for the cause, one line for the fix. After one semester, you will have a personal manual of your own recurring mistakes — and you will stop making the same ones. That log also becomes something worth showing: it is evidence that you can find and fix real problems, which is exactly what the case-study format in How to Turn GitHub Repos Into Portfolio Case Studies is built to capture.
None of this makes bugs fun. But it makes them finite. A mystery with a method ends. A panic with no method does not. The next time something breaks — and it will, probably today — skip the random changes. Reproduce it, read the error, narrow the suspects, question your assumptions, and change one thing at a time. And if you want tooling that helps with the narrowing step, ZEVQYN's GitHub code analysis lets you ask questions about your own codebase with file-level answers, which is a faster way to find where the suspect lives.