Comments and reading error messages

Two skills in this lesson, and both are about communication. Comments are how you talk to the humans who read your code. Error messages are how Python talks to you. Getting good at both will make you a calmer, faster programmer.

Comments: notes for humans

Anything after a # on a line is a comment. Python ignores it completely. Comments are there for people: other programmers, and you in a few weeks’ time.

# Work out the cost of a school trip
students = 28
cost_each = 12.5  # dollars, including the bus
print(students * cost_each)

A comment can sit on its own line or at the end of a line of code. Good comments explain why, or what a number means, not what is obvious from the code itself:

lives = 3   # bad comment: set lives to 3
lives = 3   # good comment: the original arcade game also started with 3

Switching a line off

Comments have a handy second use. Put a # in front of a line of code and Python skips it. This is called commenting out a line, and it’s a quick way to test what happens without it:

print("one")
# print("two")
print("three")

Remove the # and run again to bring line 2 back.

Errors are messages, not failures

When Python can’t carry on, it stops and prints an error message, also called a traceback. It can look alarming the first time, with all that red text, but every error message answers three questions: what went wrong, where, and often a hint about why.

Here’s a short program with a typo on line 4. Step through it and watch what happens when Python reaches the bad line.

The program got as far as line 4 and stopped. Line 5 never ran, which is why nothing was printed. A full traceback for that program looks like this:

Traceback (most recent call last):
  File "main.py", line 4, in <module>
    total = price * cuont
                    ^^^^^
NameError: name 'cuont' is not defined. Did you mean: 'count'?

Read it from the bottom up

The most useful line is the last one. Start there:

1. The last line names the kind of error (NameError) and describes it in words: there’s no such name as cuont. Recent versions of Python even guess what you meant.
2. Just above is the line of code that failed, often with ^^^^ marks pointing at the exact spot.
3. Above that is where it happened: line 4.

So: go to line 4, look at cuont, notice it should be count, fix it. Done. You’ll rarely need the rest of the traceback until your programs get bigger.

The five errors you’ll meet most

A SyntaxError is special: Python checks the whole cell before running any of it, so a syntax error means nothing runs, not even the lines above the mistake. With the other errors, the lines before the problem run normally, just like in the stepper above.

Practise reading errors

The cell below is fine. Break it on purpose, one way at a time, run it, read the last line of the error, then undo your change:

1. Delete the closing ) on the last line. (SyntaxError)
2. Change width to widht on the last line. (NameError)
3. Put quotes around the 3, so it says "3". (TypeError)
4. Change height = 4 to height = 0, and the * on the last line to /. (ZeroDivisionError)

width = 3
height = 4
print("Area:", width * height)

Doing this deliberately, while you already know the cause, is the best way to learn what each message looks like. Next time you see one by accident, you’ll recognise it.

Mistakes without error messages

The sneakiest bugs don’t produce an error at all. Remember the average that forgot its brackets in the arithmetic lesson? Python was happy; the answer was simply wrong. The cure is a habit: predict what your code should print before you run it, then compare. When the two differ, you’ve found something worth investigating. You’ll practise this properly in the lesson on tracing and debugging.

Your turn

This exercise starts with broken code. Run it, read the errors, and fix them one at a time.

length = 12
width = 5
area = lenght * width
message = "The garden is " + area + " square metres
print(message)

Check yourself