Reading and debugging

Working out what code does by following it. You rarely read a file from top to bottom. You start where the program starts, or where the problem showed up, then follow the calls, each place one piece of code starts another, and ignore everything that path never touches.

An agent can write more in a minute than you can read in an hour, so reading all of it is off the table. What you can do is follow one path through a change and ask about any step you can't explain. That is supervision, and it is what an interviewer is testing when they point at a file and say walk me through it.

A name for a value the program is holding, like a label on a box. In JavaScript, let means the name can be given a new value later, and const means it can't.

Most bugs come down to a variable not holding what someone assumed it held. When you read an agent's code, the question to keep asking is: what is in this name, right now, on this line?

A named piece of code you run by writing its name followed by brackets. It lets one idea be written once and used in many places, and it lets a reader take in the name rather than the details.

An agent that hasn't seen the function you already have will happily write a second one. Now one rule lives in two places, and the next fix only reaches one of them. So it pays to ask whether something exists before anything gets added.

Parameters are the inputs a function asks for, named in its brackets. The values you pass in are the arguments. return hands one value back to the caller and ends the function, and a function with no return hands back undefined, JavaScript's word for nothing.

A function's parameters and return value are its promise to the rest of the code. When an agent changes them, every caller is affected, including the ones it didn't read.

What kind of value something is: a number, some text (called a string), true or false (a boolean), and so on. The type decides what an operation means, so + adds two numbers but glues two strings together.

Whatever arrives from a form or an API is often text, even when it looks like a number. In plain JavaScript that gives a wrong answer with no error. TypeScript, which is JavaScript with types written in, turns it into an error before the code runs, and an agent can read that error and fix it by itself.

A condition (if) runs some code only when a test is true. A loop (for, while) repeats some code until its test turns false. Between them, they decide which lines run and how many times.

Reading an agent's code, every if is a question: what happens in the other case? A branch nobody wrote and a loop that stops a step early are where a lot of almost-right code hides.

A list, called an array, holds values in order, numbered from 0. An object holds values under names, like a small form. Both live in a box in memory, and a variable holds a pointer to the box, not what is in it.

That pointer is behind a whole family of bugs where you change a "copy" and the original changes too. Spot them by asking if the code made a new box or only a new name. JSON, from the network chapter, is these same two shapes written out as text.

A module is a file that shares some of what it defines using export. Another file pulls those parts in using import. Anything not exported stays private, so a module's insides can change without breaking the files that use it.

The import lines at the top are the quickest map of a file: they say what it depends on. They are also where agents go wrong in a way you can check, by importing a function that doesn't exist or a package nobody ever published.

Two ways JavaScript says "nothing here". undefined usually means nothing was ever set, and null usually means someone set it to nothing on purpose. Reading a property of either one crashes the program, with an error you will see often.

Agents like ?., a shortcut that skips the read when the value is missing, because it makes the crash go away. But it swaps an error you would notice for a wrong answer you might not. The real question is what should happen when the value is missing, so ask that, and then have it written down in the code.

An error that stops the current function and climbs back through whoever called it, until some code catches it using try and catch. If nothing does, the program ends.

An empty catch hides the failure from you and from every automatic check, which makes it a very easy way to turn a failure into a pass. Question any catch that does not log, retry, rethrow or tell someone.

What a crash leaves behind: the error message, then every function that was running at that moment, newest first, each with a file and a line. It is a map from where it blew up back to where it started.

It is the most precise bug report you will ever get, and it's free. Give an agent the whole thing, not your summary of it. Then check its story against the trace: if it blames a function that isn't there, it is guessing.

A class is a blueprint. Each object made from it with new gets its own data and shares the functions, called methods. Inside a method, the word this means the object it was called on.

Classes gather data and the rules for changing it in one place, and you will read plenty even if you never write one. When an agent's class grows long, ask what it holds and what changes it, because a class with many reasons to change is hard to review.

Slow work, such as a network call, doesn't hold everything up. The program gets a promise of a result and moves on. await pauses one function until its promise finishes, and other code gets to run in the meantime.

A missing await is a classic almost-right bug: the code runs, nothing errors, and it reports success before the work has happened. Look for it in anything an agent writes that saves, sends or charges.

Everything a program remembers at a given moment: its variables, what is in its database, what you have selected. The same function can behave differently depending on state, so a bug can depend on what happened before, not only on what you did just now.

Agents read code, and state is mostly not in the code. It only exists while the program runs, which is why an agent can stare at correct-looking code and find nothing. So hand it the sequence of steps, not only the symptom.

Anything a function does beyond handing back its answer: writing to a database, sending an email, changing something outside itself, even printing. A program's useful work is mostly side effects, and so is most of its risk.

An agent retrying a failed step reruns its side effects, so the email goes out twice and the card is charged twice. When you read its code, find the lines that change the outside world. Those are the ones you can't take back.

A function whose answer depends only on its inputs, and which changes nothing else. Same input, same output, every time. Code that is not pure is called impure, which is no insult: impure code does the useful work.

Pure functions are the easiest code to review, because you can understand one without knowing about the rest of the program. Asking an agent to push its logic into them is one of the cheapest ways of getting code you can check.

Scope is which names a line of code can see. A name made inside a function or a block can only be seen there. A closure is a function that keeps hold of the variables around where it was created, even after that code has finished.

Agents write functions that get called later all the time, and closures explain a whole family of bugs where one of them uses an old value. If a button acts on out-of-date data, this is the first thing to suspect.

Making the program write down what it is doing as it runs, with something like console.log. It lets you see inside a run without stopping it, and what comes back is evidence, not a theory about what happened.

Logging suits agents better than almost any other debugging tool, because an agent works by running a command and reading the output. When one starts theorising about a bug, tell it to add logs and report what they said. Then make sure it takes them out.

A tool that runs your program under your control. It pauses on a line you chose, shows you every variable and the call stack, and moves on one step at a time. Browsers have one built in, and so do most code editors.

Coding agents mostly work by running commands and reading what comes back, so pausing a live program and looking around is awkward for them. For a person it is one of the fastest ways of finding out what is really true, and being able to drive one with the agent off is worth showing.

A mark on a line that tells the debugger to pause there, so the program can run at full speed up to the part you care about. A conditional breakpoint only pauses when a test you wrote is true.

You can't press Step sixty thousand times. A condition such as price < 0 makes the machine do the searching. Working out what would only be true at the moment things go wrong is most of the skill, and that same question makes your instructions to an agent sharper.

A set of steps that makes the bug happen, ideally every time. Without one, you can't tell if a change fixed the bug or if it just didn't happen this time. A bug you can't reproduce isn't fixed, only quiet.

Agents like to jump straight to a fix, and an agent that never saw the failure can report success with nothing behind it. Make it produce the failure first, and show you. The best form of this is a failing test.

The smallest input or program that still shows the bug. You get there by removing things until the failure goes away, then putting the last thing back. What remains is often close to an explanation.

A small reproduction is cheap to hand to an agent and leaves it nothing irrelevant to chase, so you get a better answer for less.

One specific guess about the cause that a single check could prove wrong, such as "the price is already a string by line 40". Debugging goes fastest when you test one at a time and change one thing at a time.

If an agent changes five things and the bug goes away, nobody knows which one did it, and the other four stay in your code as superstition. Ask for the guess and the check before any change, because a guess you can disprove in one command is cheap.

Finding a fault by checking the middle. If things are still right there, the bug is in the later half, and if not, the earlier half. Each check rules out half of what is left, so a thousand places takes about ten checks.

It needs no understanding of the code, only a way of telling good from bad, so it still works when you are lost and the agent is too. Checking in order is the natural thing to try, and the slow one.

Explaining the problem line by line to anything at all: a colleague, a pet, a rubber duck. You often spot the mistake part way through, because explaining makes you say what you had only been assuming.

Writing a careful bug report for an agent does the same job, and you will often find the answer before you send it. It works the other way too: making an agent explain code back to you shows what it assumed, though its account of its own reasons can be a made-up story.

The symptom is what you can see going wrong. The root cause is the earliest wrong thing that produced it, and the place where a fix ends it for good. A fix at the symptom only hides it, and it comes back somewhere else.

An agent told to "fix the NaN" will do exactly that, possibly by hiding the NaN, and the test it writes will agree. Keep asking why the value was wrong until you reach the place it was created.

Being wrong by exactly one at an edge: stopping a step too early or too late, or miscounting because lists number from 0. A list of 5 has positions 0 to 4, so position 5 is off the end.

These get past casual checking, because the middle of the data is fine and only the edges break: the first item, the last item, the empty list. Agents make them too. So ask for tests at the edges, because reading the code carefully is not a reliable way of catching one.

A bug that goes away or changes when you try to look at it, because looking changes the timing or the conditions. The name is a joke on Heisenberg's uncertainty principle.

Logs and debuggers change timing, so "I added a log and now it works" is a finding, not a fix. An agent can easily report that run as a success. Look for something that depends on timing, which usually means two things sharing state.

Text in a file meant for people, which the program ignores. In JavaScript it starts with //. The useful ones say why the code is the way it is, which the code itself can't tell you.

Because the program ignores comments, nothing keeps them honest, and agents read them as fact. A stale comment misleads the next agent as well as you. Cut the ones that only repeat the line below, and keep the reasons.

Searching every file for some text or a pattern. grep is the old command, and ripgrep (rg) a fast modern one. A regular expression is a small language for patterns: \bprice\b finds the word price, but not priced.

It is how agents find their way around a codebase, and how you check what they tell you. "Nothing else calls this" is a claim you can test with one command, so test it.

A program running beside your editor that understands your code's structure. It powers go to definition, find references, rename and the red underlines. Because it follows scope and imports, it knows which of five things called total you mean.

Search shows every place a word occurs. A language server shows the places that mean this thing, and that difference matters when something gets renamed. Agents can use one as well, and it is often worth setting up for them.

When an agent tries fix after fix for the same bug, each one plausible, none of them working, some undoing the last. More attempts rarely help when its idea of the problem is wrong. This is the point at which you step in.

Stop it, go back to the last good commit, get a reproduction, halve the search, and hand back something specific you have observed, not "still broken". This is what "I can debug without the agent" means in practice, and it is a skill employers now ask about directly.