What debugging is
A bug is any difference between what a program should do and what it actually does: a wrong answer, a crash, a freeze, or a page that looks wrong. Debugging is the work of finding out why that difference exists and removing its cause.
The important word is cause. A symptom is what you notice (“the grade is wrong”); a cause is the reason behind it (“the grade was saved once and never recalculated”). Fixing a symptom hides a bug until it appears somewhere else. Fixing the cause removes it.
Bugs are not a sign of failure. Every program of any size has them, and finding them is a normal part of building software. What makes a developer good is not writing code without bugs, but having a calm, repeatable way to find and remove them.
A method for handling any bug
- Reproduce it. Find exact steps that make the bug appear every time. A bug that cannot be repeated cannot be checked as fixed.
- Describe it precisely. Write down what was expected, what actually happened, and the input that caused it.
- Narrow it down. Shrink the problem to the smallest input, the fewest steps, the one function or rule involved. Each step halves the places the cause can hide.
- Form a hypothesis and test it. Guess a cause, then prove or disprove it with a test, a printed value or a debugger, before changing anything.
- Fix the cause, not the symptom. Change the code that is actually wrong, as simply as possible.
- Add a regression test: one that fails on the old code and passes on the new, so the bug cannot return unnoticed.
- Check the neighbours. Look for the same mistake in similar code, and run the whole test suite, not just the new test.
- Record it: the problem, the cause, the fix and the lesson. A written record turns one bug into knowledge that lasts.
Where bugs come from
- Boundaries: the first and last values, empty input, the largest case (case 1).
- Stored values that go out of date: something saved once that should have been recalculated (case 2).
- Failure paths: what happens when a file is locked, a network is down or a service refuses (case 3).
- Correct but unhelpful results: the arithmetic is right, but the answer misleads (case 4).
- Presentation: the code works, but the page looks wrong (cases 5, 6 and 8).
- Tools and computers: a tool that misreads its input, or a difference between operating systems (cases 7 and 9).
Tools that make bugs visible
Boundary tests and property tests (many random cases checked against a trusted rule) find assumptions that ordinary examples never touch. Tests with real faults, such as a genuinely locked file, find hangs that simulated faults hide. Screenshots and real devices show what tests cannot see. A clear failure message, saying what was expected and what happened, often points straight to the cause.
Case studies from my projects
The nine bugs below follow the method above. Where a record confirms the cause I say so; where it only describes the fix, I say that instead.
1. GPA Tracker: Year 1 also matched Year 10
- Problem
- The discontinuation-risk check picked a year’s courses with startswith("Y1"), which also matches Y10S1. On a programme of ten or more years, a fully failed Year 1 could escape the check.
- Cause (confirmed)
- A prefix match that was too loose.
- How it was found
- Writing boundary tests for the grading rules. Every boundary behaved except this one.
- Fix
- Match "Y1S" instead, plus a regression test that fails on the old code and passes on the new.
- Result
- Not reachable with the default four-year programme, so no existing result was wrong.
- Lesson
- Boundary tests find assumptions that ordinary examples never touch, and a one-character fix still deserves a test.
2. GPA Tracker: grades went stale
- Problem
- After the weights or grade bands in the configuration changed, older courses disagreed with newer ones.
- Cause (confirmed)
- The final mark, grade and grade points were saved at entry time and never recalculated.
- Fix
- The saved coursework and exam marks became the source of truth. Grades are recalculated on every read, and a start-up repair rewrites the stored values in one transaction after taking a verified backup.
- Lesson
- Storing a value that can be derived creates a consistency problem. Keep the inputs and derive the rest, and make any repair all-or-nothing.
3. GPA Tracker: Back Up Now could freeze
- Problem
- The backup button could hang the app.
- How it was found
- Testing database failures with a real lock on the file, not a simulated one.
- Cause (confirmed)
- SQLite’s backup call retries indefinitely when the source file is locked.
- Fix
- A progress callback gives up after a few busy responses and reports a clear message. The test uses a timeout so that a returning hang is detected.
- Lesson
- Failure paths need tests with real faults, and a test for a hang must itself be able to time out.
4. GPA Tracker: the planner could advise failing
- Problem
- For low targets, the required average was mathematically correct but only reachable by failing courses, which risks discontinuation.
- How it was found
- Property tests that compared the planner with the real grading engine on random cases.
- Fix
- A “passing every course is enough” outcome when the required average is at or below the pass mark, and a test that passing never triggers the risk.
- Lesson
- A correct calculation can still give bad advice. Check what the answer means, not just whether the arithmetic is right.
5. This site: a spam-trap checkbox was visible
- Problem
- The hidden checkbox on the contact form showed above the buttons.
- Cause (confirmed)
- .contact-form input { display: block } outranked .botcheck { display: none } because of CSS specificity.
- How it was found
- Looking at a screenshot. The functional tests had passed, because the box worked correctly while being visible.
- Fix
- A more specific selector, .contact-form .botcheck, plus a test for the box being invisible.
- Lesson
- Passing tests do not prove that a page looks right. Look at it too.
6. This site: sections invisible without JavaScript
- Problem
- Sections were invisible with JavaScript off, and when printing before scrolling.
- Cause (confirmed)
- The scroll-reveal CSS set opacity: 0 on every .reveal element, and only JavaScript made them visible.
- Fix
- Hiding applies only under a js class that a small inline script adds in the head. Print and reduced-motion rules force content to show.
- Lesson
- Build the page to work first, then enhance it with JavaScript (progressive enhancement).
7. This site: the 404 page lost its styles
- Problem
- Under the security policy, the “page not found” page showed without its styles and ignored the saved theme.
- How it was found
- An automated test that loads every page under the real security policy reported two violations: one inline script and one inline style were blocked.
- Cause (confirmed)
- Inline code is allowed by a fingerprint of its exact text, which a tool works out by searching the page. A comment in the page mentioned the tag names with angle brackets, so the tool started at the comment, fingerprinted the wrong text, and the real blocks no longer matched.
- Fix
- The comment was reworded, and the tool now removes HTML comments before it searches, so no comment can mislead it again.
- Lesson
- A tool that reads code as plain text can be fooled by text that only looks like code. Make tools understand structure, and write failure messages that name exactly what was blocked.
8. This site: chips covering the portrait on phones
- Problem
- Two small decorative chips beside the portrait (“Build” and “Grow”) covered parts of the photograph.
- How it was found
- Testing the site on a real mobile phone. The automated tests had passed, because none of them checked whether one element covered another.
- Cause (confirmed)
- The chips were positioned on top of the frame’s corners. Over a plain placeholder that looked deliberate; over a real photograph it covered the picture at almost every screen width.
- Fix
- The chips moved into their own CSS grid rows above and below the frame: Build on its top-right corner, Grow on its bottom-left corner. Each one overlaps only the frame’s border, never the photo, at any width and with either portrait shape. A layout audit then measured six pages at twenty screen widths, in both themes, and found no other overlaps.
- Lesson
- Check designs on real devices, and measure layouts instead of trusting a few screenshots.
9. This site: a check that would have failed for the wrong reason
- Problem
- The automatic checks on GitHub compare generated files with a freshly generated copy. The security-policy file was written with Windows line endings, so on GitHub’s Linux machine the two copies would have differed only by invisible characters.
- How it was found
- Reviewing the check before its first run, by simulating it with Git’s line-ending conversion switched off.
- Cause (confirmed)
- The tool wrote text in the operating system’s default style: CRLF on Windows, LF on Linux.
- Fix
- The tool now always writes LF, and a .gitattributes file stores every text file with LF, whichever computer it comes from.
- Lesson
- Differences between computers are bugs too. Make generated output identical everywhere, and test a check before trusting it.