Comments

The hash mark

Everything after a # on a line is ignored by Python. It is there for whoever reads the code next, which is often you in three months.

# Work out the total including tax
price = 40
total = price * 1.2   # 20% VAT
print(total)

48.0

Commenting out code

Because Python ignores the rest of the line, a # is also how you switch a line off without deleting it:

print("this runs")
# print("this does not")
print("this runs too")

this runs
this runs too

Most editors toggle this on a whole selection with Ctrl+/ or Cmd+/.

There is no block comment

Python has no /* ... */. To comment out ten lines you put a # in front of each one, and your editor does it for you.

You will sometimes see a triple-quoted string used for the job:

"""
This is a string that nobody uses.
Python builds it, then throws it away.
"""
print("done")

done

That works, but it is a string being evaluated and discarded rather than a comment. It is fine at the top of a file and a bad habit in the middle of a function.

Docstrings

A string on the first line of a function, class or file is a docstring. Python keeps it, and tools read it:

def area(width, height):
    """Return the area of a rectangle."""
    return width * height

print(area(3, 4))
print(area.__doc__)

12
Return the area of a rectangle.

That is the difference worth remembering: a comment is thrown away, a docstring is part of the object and help() can find it.

Write comments that earn their place

A comment repeating what the code already says is noise, and it goes stale:

# add one to count
count = 0
count = count + 1
print(count)

1

The useful comment explains why, not what:

# The API rejects more than 50 ids per call, so send them in batches
batch_size = 50
print(batch_size)

50