Python Comments: explain your code without changing its output

A school notice program may be easy to read today. A month later, another teacher might wonder why you chose that message or where a number came from. A comment is a note in the source code for a person reading it. Python does not execute ordinary comments as instructions, and they do not appear in the program’s output.

In Python, a # outside a quoted string starts a comment that continues to the end of that line. You already know how to display text from the Hello World lesson; now we can put a useful note beside that code.

# Welcome students arriving for the new term.

print("Welcome to Class 6!")

Welcome to Class 6!

Here is the complete Python 3 program shown in the illustration. Run it in the Python online compiler.

# Welcome students arriving for the new term.
print("Welcome to Class 6!")

Expected output

Welcome to Class 6!

The first line gives a human reader context. Its # makes the rest of that line a comment. The second line is a normal print call, so Python displays its quoted text. Removing the first line would leave this output unchanged.

A comment can contain ordinary words and punctuation without quotes. It still belongs in the source file; use print when the person running your program needs to see a message.

An inline comment follows code on the same line. Python reads the instruction before the comment; the comment does not switch off that earlier instruction.

print("The library opens at 9.")  # Opening time during term.

Expected output

The library opens at 9.

Finish the print call, leave two spaces, then write #, a space and the note. The spacing makes the two parts easier to distinguish and follows Python’s inline-comment style guidance.

Keep an inline note short. If the explanation needs several sentences, place it above the instruction instead.

The school register records how many students were absent. In this Python 3 example, absent_students is a name for that count. The = instruction gives the name its value; print(absent_students) displays the value. We will study names more fully in Python variables.

Choose a count and predict the output. The note above the code explains why we need it, and the inline note says where it came from. Watch which lines change a value or produce output.

Compare these complete Python 3 programs. Each note is different, but the instruction is identical.

First note

# Welcome students arriving for the new term.
print("Welcome to Class 6!")

Rewritten note

# This greeting appears on the classroom noticeboard.
print("Welcome to Class 6!")

Expected output

Welcome to Class 6!

Both programs produce that output. Changing a comment changes the explanation, not the welcome. To welcome Class 7 instead, change the text in the instruction:

# This greeting appears on the classroom noticeboard.
print("Welcome to Class 7!")

Expected output

Welcome to Class 7!

This distinction matters when fixing a program: a corrected note cannot repair an incorrect instruction.

A # does not always start a comment. Inside a quoted string, it is text. Read this Python 3 example from left to right:

print("Meet at desk #3.")  # Desk numbers are printed on signs.

Expected output

Meet at desk #3.

The first hash sits inside the matching quotes, so it becomes part of the displayed message. The second hash is outside the string and begins the comment. Python does not print the note about desk signs.

The Python language reference defines this boundary: a comment begins at a hash that is outside a string and ends with the physical line.

Python has no ordinary comment marker that opens a whole multi-line block. For a longer note, start each line with #. Here the note explains a temporary school arrangement.

# The main library entrance is closed for repairs.
# Direct students to the side entrance this week.
print("Use the side entrance for the library.")

Expected output

Use the side entrance for the library.

Each hash covers only its own line. If you remove the hash from the second note, those words become attempted Python code and this program will fail to run. A blank line does not extend a comment either.

To comment out an instruction, put a hash before it. That makes the entire instruction part of a comment. This Python 3 program keeps an old notice in the file while displaying its replacement:

# print("Use the main library entrance.")
print("Use the side entrance for the library.")

Expected output

Use the side entrance for the library.

Only the second print call runs. This can help you compare a small change while experimenting. Most editors can toggle comments on selected lines; the shortcut depends on the editor.

Do not keep growing piles of disabled old code in the finished program. They make the current behavior harder to find. Also remember that comments remain readable in your source file: they are not a place to hide passwords or private student information.

You may see triple quotes recommended for “multi-line comments.” That wording is misleading: triple quotes create a string, which is a text value. A string can contain line breaks and can be displayed or used by the program.

print("""Library notice
Use the side entrance.""")

Expected output

Library notice
Use the side entrance.

This Python 3 program prints the multi-line string. A stand-alone string that is not used may produce no visible output when a file runs, but it is still a string expression. Use hashes for ordinary notes.

A docstring has a specific job

A docstring is a string in the first statement of a module, function or class that documents it. A module is a Python file; functions and classes come later in the course. Here is a complete module example to save and run as a Python 3 file:

"""Display the school library notice."""
print(__doc__)

Expected output

Display the school library notice.

__doc__ is a special name through which Python makes this module’s documentation available. The print call retrieves and displays it. You do not need to memorize that name yet; it demonstrates why a docstring is different from an ignored hash comment. See the official documentation-string explanation and revisit this idea when you learn Python functions.

A useful comment answers a question the code does not answer by itself: why this choice, where this information came from, or what limitation a future reader should remember.

A note that repeats the instruction

print("Use the side entrance.")  # Print use the side entrance.

A note that supplies a reason

# The main entrance is closed for repairs this week.
print("Use the side entrance.")

Expected output

Use the side entrance.

The second program tells another teacher why the notice exists. In an early lesson, explaining unfamiliar syntax can be helpful too; you do not need a rule that comments must only ever explain “why.” As the code becomes familiar, remove notes that no longer help.

When the entrance reopens, update both the instruction and its explanation. An outdated comment can mislead the next reader even while the code runs successfully.

The classroom changes from Class 6 to Class 7. This Python 3 program is out of date:

# Welcome Class 6 students on their first day.
print("Welcome to Class 6!")
# print("Please bring your notebook.")

Your task: update the class in both the note and the greeting, then make the notebook reminder run. Predict both output lines before running your version.

Worked answer

# Welcome Class 7 students on their first day.
print("Welcome to Class 7!")
print("Please bring your notebook.")

Expected output

Welcome to Class 7!
Please bring your notebook.

We updated the comment to keep it truthful, changed the quoted message to affect the greeting, and removed the hash before the final print call to enable the reminder. Editing only the note would still welcome Class 6.

Read the complete Python 3 program:

print("Queue at desk #2.")  # Collect your library card here.

# Welcome Class 7.
print("Welcome to Class 6!")

You need two lines explaining a temporary library closure. The explanation should be an ordinary comment rather than a text value.

You can now explain a program to another person without accidentally changing what it displays.

• Ordinary comments: a hash outside a string starts a note that ends with that line.
• Inline comments: code before the hash still runs. A hash inside quoted text is part of that text.
• Longer notes: start each comment line with its own hash. Commenting out a print call prevents that call from running.
• Strings and documentation: triple quotes make strings; a docstring documents a module, function or class in a specific position.
• Maintenance: explain useful context and revise the note when the program changes.

Before moving on, write a two-line classroom notice with one useful comment, predict the displayed messages, and check that editing the comment alone leaves them unchanged.