Describing a Bug Clearly
Imagine calling a mechanic and saying 'my car is broken.' They will ask you a series of questions: What noise? When? Under what conditions? What did you already try? A good bug description gives all of that upfront. Whether you are asking a classmate, a teacher, or an AI for help, the quality of your description determines the quality of the help you get. Vague descriptions produce vague fixes.
The Three-Part Formula
A clear bug description has three parts, and every effective description has all three. Part 1 — What I expected: Describe precisely what you wanted to happen. 'I expected the total score to appear in the score box after clicking Submit.' Part 2 — What actually happened: Describe exactly what occurred instead. 'The score box stayed empty and the browser console showed a TypeError on line 42.' Part 3 — What I already tried: List anything you changed or checked. 'I verified the variable name is spelled correctly. I tried moving the function call earlier. The problem still happens.' That three-part structure is enough to help almost anyone — human or AI — start investigating immediately. It eliminates the back-and-forth of 'what did you expect?' and 'what does the error say?'
Expected behavior + Actual behavior + What you already tried. These three pieces contain nearly everything a helper needs to narrow the problem. Leave any one out and you are handing them a puzzle with missing pieces.
Compare these two descriptions of the same bug: Weak: 'My quiz app is not working. Can you fix it?' Strong: 'My quiz app should display the final score after the user clicks Submit. Instead, the score always shows as 0. I confirmed the score variable is updated correctly in calculateScore(), but it seems like displayScore() is not receiving the updated value. The error is: TypeError: Cannot read properties of undefined at displayScore (quiz.js:58).' The strong description does not just tell the helper there is a problem — it tells them where the problem probably is, what is ruled out, and what the computer said about it. A helper reading that can skip the investigation phase and move straight to proposing a fix.
Complete the three-part bug description formula.
Precision vs. Guessing
There is a trap in bug descriptions: explaining what you think the cause is instead of what you observed. 'I think the function is broken' is a guess. 'The function returned undefined when I passed it the number 5' is an observation. Both might be true, but only one is useful to a helper. When you write a bug description, separate your observations (facts) from your hypotheses (guesses). You can include your guess — it might be right — but label it clearly: 'I observed X. My guess is Y, but I am not sure.'
Lead with what you saw, not what you think. Then add your hypothesis as a clearly labeled guess. A good helper will check your guess against your observations and catch it if you are wrong.
Which bug description would be most useful to a helper?
Why is it important to separate observations from guesses in a bug description?
Turn a Weak Description Into a Strong One
- Here is a weak bug description: 'My game crashes sometimes when I press the jump button.'
- Rewrite it using the three-part formula:
- 1. Write what the expected behavior should be (you can invent reasonable details).
- 2. Write what actually happens, including any error message you might see.
- 3. Write two or three things you already tried.
- Compare your rewrite with a partner. Did you end up with something a helper could act on immediately?
- Bonus: swap descriptions and write back one specific question you would still need answered before you could help fix it.