{module 1}
Debugging and asking for help
Orientation15 min read
What you will be able to do
- Open the browser's Console, read an error message, and say which file, which line and what kind of problem it names.
- Follow the five steps of the debugging loop.
- Write a question in three parts that another person, or the AI assistant, can answer.
Why it matters
Bayou Bikes is a bicycle repair shop in New Orleans, United States. The owner's nephew, Andre, was making a small page that shows the price of a repair. He opened it in his browser and pressed the button. Nothing happened. He decided he was not clever enough for programming and closed the laptop for a week.
The browser had written a message the first time he pressed the button. It said that he had typed cots where he meant cost. He never saw it, because he did not know where browsers keep their messages. Reading it would have taken thirty seconds.
Every programmer sees errors every day. The difference between a beginner and a professional is not that the professional makes fewer mistakes. It is that the professional has a routine for them. This lesson gives you that routine before you write your first line, so that the first error you see is something to read and not something to fear.
The idea
An error is a message
A web page can contain a script, a small program written in JavaScript that makes the page respond. When a script cannot continue, it stops and the browser writes an error message. The visitor sees no message. The message goes to the Console, a panel in the browser where pages write messages for the people who build them.
The message usually tells you four things: the file, the line, the kind of problem, and a short description. You will see a real one in the worked example.
Finding and fixing the cause of an error is called debugging. A bug is the mistake itself.
Opening the Console
The Console is part of the browser's developer tools, a set of panels for looking inside a page. Module 1 teaches them properly. For now you only need to open the Console:
- In Chrome or Edge, press Ctrl+Shift+J on Windows or Linux, or Cmd+Option+J on a Mac.
- In Firefox, press Ctrl+Shift+K on Windows or Linux, or Cmd+Option+K on a Mac.
To close it, select the X in the top right corner of the panel.
The debugging loop
Debugging is a skill with five steps. Use them in this order, every time.
- Read the error. All of it. Find the file, the line and the description.
- Reproduce it. Make the error happen again, on purpose. If you cannot make it happen twice, you cannot know that you fixed it.
- Form one guess about the cause. One, not three. Say it as a sentence: "I think the name on line 8 is spelled wrong."
- Test the guess. Change one thing, save the file, reload the page and try again. The browser shows the file as it was when the page was loaded, so a change you do not save and reload tests nothing. If the error is gone, your guess was right. If it is the same, undo the change and form a new guess.
- Search the official documentation. If two guesses fail, look up the exact words of the error in the documentation of the language or tool you are using, before you look anywhere else.
The step that people break is the third one. They change four things at once, the error goes away, and they do not know which change fixed it. Or the error stays, and now they have four new changes to worry about.
A good question has three parts
Sometimes the loop is not enough and you need to ask. A question that gets a useful answer has three parts.
- What you want to happen. "I want the page to show the repair cost when I press the button."
- What happens instead, exactly. What you did, what the page did, and the exact message in the Console, copied and not described.
- What you already tried. Your guesses and what each one changed.
"It does not work" has none of the three. Nobody can answer it, however much they want to help.
Using the AI assistant
Every lesson and project has an AI assistant. It is useful, and it is easy to use badly.
- Ask for a hint, not the answer. "Give me a hint about what this error means" teaches you. "Fix my code" gives you working code and nothing you can use next time.
- Give it the three parts. It cannot see your screen. Paste the message from the Console and say what you tried.
- Check what it says. It can be wrong, and it says wrong things in the same confident voice as right things. Try its suggestion. Look up the idea in the official documentation.
- It has a daily limit. Use the debugging loop first and keep the assistant for when you are stuck.
Worked example
Here is Andre's page. You do not need to understand every word yet. It is two files in one folder. The first is the page itself:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Bayou Bikes: repair price</title>
<script src="repair.js" defer></script>
</head>
<body>
<h1>Bayou Bikes</h1>
<p>A two-hour repair at $15 an hour.</p>
<button id="price-button">Show the price</button>
<p id="price"></p>
</body>
</html>The second is the script. When the button is pressed, it should work out the cost of two hours at $15 an hour and write it on the page:
const button = document.querySelector("#price-button");
const price = document.querySelector("#price");
button.addEventListener("click", () => {
const hours = 2;
const rate = 15;
const cost = hours * rate;
price.textContent = "Repair cost: $" + cots;
});Andre opens repair.html in his browser. This is the text the page shows:
Bayou Bikes
A two-hour repair at $15 an hour.
Show the priceHe presses "Show the price". No price appears. He opens the Console, and it shows this line in red:
Uncaught ReferenceError: cots is not definedAt the right end of the same line, the Console names the file and the line: repair.js:8.
Now the loop.
Read. repair.js:8 is the file and the line number: line 8 of repair.js. Then comes the description. Uncaught means that nothing in the script dealt with the problem, so the script stopped. A ReferenceError means the script met a name it does not know. The name is cots.
Reproduce. Reload the page and press the button again. The same message appears in the Console again. Good: the error is stable.
One guess. "I think cots is a spelling mistake for cost, which is defined on line 7."
Test. In repair.js, change cots to cost on line 8. Change nothing else. Save the file, reload the page and press the button. The page now shows:
Repair cost: $30The Console has no new message, and the answer is right: 2 hours at $15 is $30. The guess was correct, so there is no need for the fifth step this time.
Common mistakes
Looking only at the page. A page does not show its errors. You see a button that does nothing or a missing part. Open the Console before you guess.
Describing the error in your own words. "It says something about a reference" loses the one word that matters, cots. Copy the message exactly. Do not retype it.
Changing several things at once. If you fix the spelling, rename rate and add a line, and the page now works, you have learned nothing about which change mattered. One guess, one change.
Think it through
Zanele's page shows Total: NaN where she expected the total of three prices, and the Console shows no message at all. She has tried two guesses and both failed. She needs to ask for help. How does she write the question?
Understand. The goal is not "get someone to fix it". The goal is a question that a stranger can answer without seeing her screen.
Break down. Three parts: what she wants, what happens instead, and what she tried.
Plan. Write one sentence for the first part. Say what she did and copy what the page showed for the second. List the two guesses for the third.
Build. "I want my page to show the total of three prices when I press Add up. I opened total.html in Chrome and pressed the button. It shows Total: NaN, and the Console has no message. I checked that all three prices are on the page, and they are. I replaced the plus sign with a minus sign, and it still shows NaN."
Test. She reads it as a stranger would. Could they answer? Not yet, because they cannot see the code. She adds the few lines of her script.
Reflect. Writing the third part made her look at her guesses again, and she noticed that she never checked what kind of value each price was. Often, writing the question is what finds the answer.
At work
A good question is a professional skill, and the three parts are the same when you ask a colleague or a client. People who are busy answer the questions that are easy to answer.
Compare two messages to a more experienced developer:
The booking page is broken, can you look?
I want the booking page to show the order total. Since this morning it shows $0.00 for every order. I checked the Console, and it has no message. I checked that every item on the page has a price, and it does. I have not yet checked the script. Could you tell me which part of the script works out the total?
The second one took three minutes to write and will be answered in one. It also shows that you tried first, which is what makes people willing to help you the next time.
Your tasks
Task 1: Read an error
Look at the Console message in the worked example again. On paper, write the answers to four questions. Which file? Which line? What kind of error? Which name does the script not know?
You are done when you have four answers, and each one is a word or number copied from the message.
Task 2: Find the Console
Open any web page, then open the Console with the keys for your browser. Look at what is there, then close it.
You are done when you can open the Console without looking up the keys, and close it again.
Task 3: Repair a bad question
A learner writes: "My page looks wrong on my phone. Please help." Rewrite it as a question with the three parts. You may invent the details, such as what the page should look like and what the learner tried.
You are done when your question says what should happen, what happens instead and what was tried, and a stranger could start to answer it.
Task 4: Ask the assistant for a hint
Open the AI assistant on this lesson. Ask it one question about something in this lesson that you want explained further, and ask for a hint or an explanation, not an answer to a task. Then check one thing it told you against a page in "Go deeper".
You are done when you have written down what the assistant said and whether the page you checked agrees with it.
Recap
- When a page does not do what it should, open the Console. Its error message names the file, the line and the problem.
- The debugging loop is: read, reproduce, one guess, test the guess, search the official documentation.
- Change one thing at a time, save, and reload, so you know what fixed it.
- A good question says what you want, what happens instead, exactly, and what you tried.
- Ask the AI assistant for hints, give it the three parts, and check what it says.
Go deeper
- Chrome DevTools: Console overview shows what the Console is for and how to view the messages a page writes there.
- MDN: What went wrong? Troubleshooting JavaScript walks through finding and fixing errors in a small page.
- MDN: JavaScript error reference lists error messages and what each one means.
- Stack Overflow: How do I ask a good question? is the guide that a large community of programmers uses.