Computer Science & Data: Flowchart my debugging process

What you'll be able to do: Describe how you actually debug, have it drawn back as a flow, and discover that you don't have a procedure, which is the finding.

The exercise

Describe, in a paragraph, what you do when something doesn't work. Then have it rendered as a flowchart with explicit decision points, with gaps marked rather than filled in.

Almost everyone's first attempt produces a chart with one box in the middle labelled something like "look at the code again" and no branches out of it.

That box is the finding. It's where a procedure should be and isn't.

Why prose hides this and a chart can't

"Then I check whether the input is what I expect and go from there" reads as a complete instruction and specifies nothing. Check how? What counts as expected? And what are the two branches, what do you do if it is, and if it isn't?

A flowchart won't accept that. Every decision node needs a condition; every branch needs a destination. The places where you can't supply them are exactly where your procedural knowledge stops: and in debugging, that's usually everywhere after "read the error message".

This is the procedural counterpart to sketch critique (article 04 of the sciences): that diagnoses your picture of a system, this diagnoses your picture of a procedure. Programming assesses both and teaches neither explicitly.

The prompt

I'm going to describe how I debug. Turn it into a flowchart with explicit decision points and branches. Where my description doesn't specify a condition, or leaves a branch without a destination, mark it as a GAP rather than filling it in yourself.

Then, and only then:

For each gap, ask me what I'd actually do there. Don't tell me.

And the test:

Give me three bugs that would take unusual paths through my flowchart, including at least one it can't handle at all.

What a real debugging procedure contains

If your chart is missing these, that's what to add, and each is a decision you currently make by instinct:

• Reproduce reliably. Can you make it fail on demand? If not, that's the first problem and it's a different one.
• Minimise. What's the smallest input or code path that still fails? This is the highest-value move in debugging and the most commonly skipped.
• Form a hypothesis. Specifically: I think X, because Y. Not "something's wrong with the loop."
• Choose the cheapest discriminating test. What can you check that would rule out half the possibilities?
• A branch for "hypothesis was wrong." This is the branch nobody draws, and debugging is mostly this branch. A chart that only goes forward is a description of a lucky session, not a procedure.
• A stopping rule. When do you stop and ask, or take a break, or rewrite the thing instead of fixing it? Without this, people grind for three hours.
• Confirm the fix explains the symptom. Not just that it works now, that the explanation accounts for what you saw. A fix that works for an unknown reason is a bug you've displaced.

That last one catches the most dangerous outcome in debugging: it went away and I don't know why.

Across the subject

Runtime errors. The chart is short and mostly works. Good place to start.

Silent wrong output. Where most charts fall apart, there's no error message to anchor on, so the procedure has to be constructed rather than triggered.

Intermittent failures. The reproduce step becomes the whole problem, and most students' charts don't have one.

Performance problems. An entirely different procedure, measure first, never guess, and most people have no chart for it at all.

Data pipeline bugs. The chart needs a "which stage?" bisection step. Most students check the last stage repeatedly.

ML models underperforming. Needs a branch that distinguishes bug, data problem, and model-is-fine-expectations-were-wrong. Without it, people tune hyperparameters at a data leak.

The comparison worth making

Once you've drawn yours, draw one for a domain where you do have a procedure, how you find a fault in a circuit, or how you look something up. The difference in resolution is instructive, and it shows that the vagueness is specific to debugging rather than general to you.

Pitfalls

1. Letting the gaps be filled in. The gaps are the finding.
2. Charting an idealised process. Describe what you actually do, including the guessing and the re-reading. A chart of your intentions diagnoses nothing.
3. No failure branches. Real debugging is mostly the "that didn't work" path.
4. No stopping rule. The absence of one is why sessions become three hours.
5. The tell: your chart has a box that says "figure out what's wrong". That's the whole problem restated as a step.

Try this today

Write one paragraph describing how you debug. Have it charted with gaps marked, not filled.

Count the gaps. Then add the two branches almost nobody has: hypothesis was wrong and stop.