The Bug Log

One-sentence summary

A bug log is a table where you record every bug you find in your project — with its date, symptom, cause, fix and status — so that you never forget a bug and you learn something from each one.

Why does it matter?

When you run your test scenarios, sooner or later you will hit a bug. Your first instinct is, “Fine, I will just remember this one.” But half an hour later you have found three more bugs and forgotten the first. Then presentation day arrives, the same bug shows up again, and you think, “Wait, didn’t I already fix this?”

A bug log prevents exactly that. Instead of trusting your memory, you trust a record. That record has three benefits:

• You do not forget. Every bug you find is written down, so none of them slip away.
• You learn. When you see similar bugs next to each other, you notice a pattern — something like “most of my connection bugs were just loose cables.”
• You can show it. When an adult or a teammate asks “What has happened so far?”, you can answer with a single table.

Professional software and engineering teams do the same thing. They call it a *bug tracker*. What you are about to do is exactly that, on a smaller scale.

What goes into a bug log?

In the Debugging lesson we learned how to *find and fix* a bug. A bug log is how you *record* that work. The two go together: first you debug, then you write down what you did.

In a good bug log, each row describes one bug and includes this information:

An ID and a date

Give each bug a short number (B1, B2, B3…) and write down the date you found it. The number makes it easy to talk about bugs: saying “Is B2 still open?” is faster than describing the whole thing.

Symptom

The symptom is what you observed — that is, what looks wrong. Do not try to guess the cause here; just write what actually happened. “The night light does not turn on in the dark” is a symptom. “The sensor is broken” is not, because you do not know that yet.

Cause

The cause is the real source you find after investigating. You usually cannot write it right away; first you debug, then you fill it in. “The light threshold was set too low” is a cause.

Fix

Once you find the cause, write what you did. Be specific, like “I raised the threshold from 300 to 600.” Writing “fixed it” is not enough; if the same bug returns later, you need to remember what you actually did.

Status

Every bug has a status. Three simple states are enough:

• Open: The bug exists and has not been solved yet.
• In progress: You are working on it.
• Closed: It is solved and confirmed with a test scenario.

You only mark a bug “Closed” after you test it again and see that it is really fixed. Closing a bug without re-testing is one of the most common mistakes.

Example: An automatic night light log

Think about the automatic night light project from earlier modules: the LED turns on when it gets dark and turns off when it is light. You ran your test scenarios and found some bugs. Here is what your log might look like:

This table tells you a lot. B1 and B2 are closed, so the project is moving forward. B3 is open and its cause is still unknown; that is your next debugging job. You are working on B4 but you are not sure yet, so you wrote “Testing” and left the status as “In progress.”

Notice that B3’s cause and fix are empty. That is completely normal. A log is not born complete; the rows fill in as you debug.

A second example: A line-following robot log

The same method works on a project with more complex hardware. Here are bugs you might meet while testing your line-following robot:

Look at R2: the symptom is “drives backwards,” and the cause is “wires reversed.” Because you wrote the symptom and the cause separately, if you ever see the same symptom on another robot you will know where to look first. That is the part of a log that teaches you.

Mini practice

Pick one of your own projects (or a project you dream of building) and prepare an empty bug-log template. You can copy the template below:

PROJECT: ____________________
START DATE: __________

No | Date | Symptom | Cause | Fix | Status
---|------|---------|-------|-----|-------
B1 |      |         |       |     | Open
B2 |      |         |       |     | Open
B3 |      |         |       |     | Open

STATUS OPTIONS: Open / In progress / Closed
RULE: Only mark a bug "Closed" after you re-test and see it is fixed.

Then try this: during your next test, log the first bug you find in this table. Write only the symptom, and leave the cause and fix empty. As you debug, fill in the other columns. That way your log becomes a living record.

Common mistakes

Mixing up symptom and cause

If you write “sensor is broken,” that is a guess, not an observation. Maybe the sensor is fine and the problem is the cable. First write what you actually saw (the symptom), then add the cause after you investigate.

Writing the fix vaguely

Writing “fixed it” is useless. If the same bug appears three months later, that note tells you nothing. Be concrete, like “set the threshold to 600.”

Closing without testing

Making a change does not mean the bug is solved. Do not set the status to “Closed” until you run the test scenario again and see that it is fixed.

Being too lazy to log small bugs

You say “this is tiny, not worth writing down,” and that tiny bug shows up on presentation day. Small or large, record every bug.

Trying to fill the log in later

Your memory forgets half the bug. The moment you find a bug, fill in at least the symptom column.

Safety note

Your bug log is usually a technical record that only matters to you. Still, when you share it with someone else (a teacher, a teammate) or show it in a presentation, make sure you have not written personal information in it: your full name, home address, school name, or other people’s details should not appear in the log. Keep your notes about the project, not about you. Also, when investigating hardware bugs, ask an adult for help before touching parts like hot surfaces, batteries and motors.

Lesson summary

• A bug log is a table that records every bug found, with its date, symptom, cause, fix and status.
• The symptom is what you observed; the cause is the real source you find after investigating — do not mix them up.
• Every bug has a status: Open, In progress or Closed.
• You only close a bug after you re-test it and see that it is really fixed.
• A log keeps you from forgetting bugs and, over time, helps you spot patterns and learn.

Check questions

1. What five pieces of information should each row of a bug log contain?
2. What is the difference between a “symptom” and a “cause”? Give an example of each.
3. When are you allowed to move a bug to the “Closed” status?
4. Why is writing “fixed it” in the fix column not enough?
5. Is it a problem if a newly found bug has empty cause and fix columns? Why?

Answers

1. An ID/number and a date, the symptom, the cause, the fix, and the status. (If you count the number and date as one item: date, symptom, cause, fix, status.)
2. The symptom is the wrong-looking thing you observe (“LED does not turn on in the dark”). The cause is the real source you find after investigating (“the light threshold was set too low”). The symptom is an observation; the cause is an explanation.
3. Only after you make a change, run the relevant test scenario again, and see that the bug has really disappeared.
4. Because if the same bug returns later, the note “fixed it” will not remind you what you did. A concrete fix (“set the threshold to 600”) is both reusable and explainable to someone else.
5. It is not a problem. A log fills in as you debug. For a new bug you first write only the symptom, and you add the cause and fix once your investigation is finished.

Source and verification note

For “The Bug Log”, verification focuses on whether the relationship between What goes into a bug log? and Symptom remains consistent across examples. A project page should make a result claim only when it is supported by a real prototype, test record or observation. Numbers such as cost, duration and success rate must be labelled clearly when they are estimates.

Next lesson

Improving: After you close your bugs, which steps do you follow to move the project from just “working” to genuinely “better”?