Python Comments

Code tells the computer what to do, but it doesn't always tell a human why. That's the job of Python comments: short notes inside your code that Python skips completely. In this lesson, you'll learn how to write comments, when to use them, and how to tell a helpful comment from a useless one.

What is a comment in Python?

A comment is any text that starts with a hash sign # (also called a pound sign or number sign). When Python reads your file, it ignores everything from the # to the end of that line.

# Work out a 20% tip for a restaurant bill
bill = 50
tip = bill * 0.2
print("Tip:", tip)

Tip: 10.0

The first line has no effect on the program at all. It's there only to help whoever reads the code, which is often you, a few months from now.

How do you write a single-line comment?

Type #, a space, and your note. The space isn't required, but the style guide (PEP 8) recommends it because it's easier to read.

# Prices are in US dollars
latte = 4.50
muffin = 3.00

# Show the total for one latte and one muffin
print(latte + muffin)

7.5

A comment goes on its own line, usually just above the code it describes, and it uses the same indentation as that code.

What is an inline comment?

An inline comment sits at the end of a line of code. Python runs the code part and ignores everything after the #.

speed_limit = 65  # miles per hour, US highway
max_bags = 2      # checked bags included in the ticket
print(speed_limit, max_bags)

65 2

PEP 8 suggests at least two spaces before the #. Inline comments are great for short facts like units, but keep them brief. If you need a full sentence, put the comment on its own line above.

How do you write multi-line comments in Python?

Python has no special symbol for a multi-line comment like /* ... */ in JavaScript or C. Instead, you start every line with #:

# Weekly allowance calculator.
# Kids get $5 a week, plus $1 for every
# chore they finish.
allowance = 5
chores_done = 3
print(allowance + chores_done)

8

Are triple-quoted strings comments?

You'll often see people use triple quotes (""" or ''') to write notes across several lines:

"""
This looks like a comment,
but it's actually a string.
"""
print("Hello")

Hello

Here's the honest truth: this is not a real comment. It's a string value that isn't stored in any variable, so it has no visible effect. It works, but there are two differences you should know about:

• A string must follow indentation rules; a comment doesn't. Python skips # lines completely, but a string is real code.
• In certain places, a string has a special job. As the first line inside a function, it becomes a docstring, which is official documentation Python stores and shows in help().

This works fine, because a # comment can sit at any indentation:

if True:
# check the weather later
    print("Sunny")

Sunny

But the same note written as a string breaks the program:

if True:
"""check the weather later"""
    print("Sunny")

IndentationError: expected an indented block after 'if' statement on line 1

Here's a quick preview of a docstring. You'll learn about functions (def) later in the course:

def greet(name):
    """Return a friendly greeting for the given name."""
    return "Hi, " + name + "!"

print(greet("Maya"))
print(greet.__doc__)

Hi, Maya!
Return a friendly greeting for the given name.

Commenting out code for debugging

Comments aren't only for notes. You can put a # in front of a line of code to switch it off temporarily. This is called commenting out code, and it's a handy way to test what happens without a line, without deleting it.

price = 20
discount = 5
# price = price - discount
print(price)

20

Remove the # and the discount line runs again. Once you've found the problem, clean up: don't leave large blocks of dead code commented out forever.

Keyboard shortcut to comment lines

Most editors can comment or uncomment several lines at once. Select the lines and press:

• Ctrl + / on Windows and Linux
• Cmd + / on macOS

This works in VS Code, PyCharm and many other editors. Press it again to remove the # signs.

What makes a good comment?

The code already says what it does. A good comment explains why: the reason, the business rule, or the surprise a reader wouldn't guess.

A few more habits help:

• Prefer clear names over comments. minutes_left = 15 needs no comment; m = 15 # minutes left does.
• Keep comments up to date. A comment that no longer matches the code is worse than no comment.
• Write in plain, short sentences so anyone on your team can follow.

The TODO comment convention

Developers often mark unfinished work with # TODO:. Many editors highlight these comments and can list them all for you, so nothing gets forgotten.

subtotal = 120
# TODO: add sales tax for orders outside the US
print("Total:", subtotal)

Total: 120

You may also see # FIXME: for a known bug that still needs fixing.

Common mistakes with comments

1. Forgetting the #

Calculate the total price
total = 10 + 5

SyntaxError: invalid syntax

Without the #, Python tries to run your note as code.

2. Using comment symbols from other languages

// total price
total = 10 + 5

SyntaxError: invalid syntax

// starts a comment in JavaScript, Java and C, but in Python it's the floor division operator. Python comments always use #.

3. Commenting every single line

Too many comments bury the useful ones. If every line needs explaining, try clearer variable names first.

Practice exercise

monthly_fee = 40
member_price = monthly_fee * 0.9
print("Member price:", member_price)
print("Debug: fee was", monthly_fee)

# Show the monthly gym price for members
monthly_fee = 40
member_price = monthly_fee * 0.9  # members get 10% off
print("Member price:", member_price)
# print("Debug: fee was", monthly_fee)

Member price: 36.0

What's next?

Now your code can explain itself. Next, learn how to store and reuse values with Python variables.