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

Where bugs come from

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.