LearnContact
Lesson 615 min read

Comments

Learn how to write single-line and multi-line comments in Python, understand docstrings, and follow PEP 8 guidance for writing comments that actually help.

Introduction

Code tells a computer what to do, but it does not always explain why. Comments are notes written directly inside your code that the Python interpreter ignores completely — they exist purely for humans reading the code, including your future self.

This lesson covers how to write single-line and multi-line comments, what docstrings are, and the etiquette around writing comments that are actually useful rather than just noise.

What You Will Learn
  • How to write single-line comments with #.
  • Techniques for writing multi-line comments.
  • What a docstring is and how it differs from a regular comment.
  • Why good comments explain "why," not "what."
  • PEP 8's guidance on comment style.

Single-Line Comments

The most common way to write a comment in Python is with the hash symbol (#). Everything after a # on that line is ignored by the interpreter — it can start the line entirely, or follow actual code on the same line.

# Full-line Comment

A # at the start of a line comments out the entire line.

code # inline comment

A # after real code comments out only the remaining part of that line.

Ignored by Python

The interpreter skips comments completely — they have zero effect on execution.

Example: Using # Comments

Both full-line and inline comments are demonstrated below. Notice the program's output is unaffected by either comment.

comments_basic.py
# This program calculates the total price of an order
price = 250
quantity = 4

total = price * quantity  # multiply price by quantity
print("Total:", total)
Output
Total: 1000

Multi-Line Comments

Python has no dedicated syntax for a "block comment" the way some languages do. The standard way to comment out multiple lines is simply to start each line with its own # symbol.

Multiple # lines
# This section handles the order total
# It multiplies price by quantity
# and then prints the result
price = 250
quantity = 4
print(price * quantity)
Output
1000

Example: The Triple-Quote Trick

You will sometimes see triple-quoted text ('''...''' or """...""") used to comment out a block of code. Technically, this is not a comment at all — it is a string literal that Python creates and then simply discards if it is not assigned to anything or used as a docstring.

triple_quote_trick.py
"""
This whole block is technically a string,
not a real comment, but it is commonly
used to temporarily disable a section of code.
"""
print("This still runs")
Output
This still runs

Because this creates an actual string value in memory (even if unused), the official, purpose-built way to comment code remains the # symbol. The triple-quote trick is best reserved for temporarily disabling a block during testing.

Docstrings

A docstring is a special, structured form of documentation written as the very first statement inside a function, module, or class, using triple quotes. Unlike a regular comment, Python actually recognizes a docstring and stores it, making it accessible through documentation tools and the built-in help() function.

Docstrings are covered in full detail in the lessons on functions. For now, it is enough to know they exist as a special, more powerful cousin of the comment, specifically for documenting what a function, class, or module does.

Comments vs Docstrings
  • A regular comment (#) is only readable in the source code itself.
  • A docstring is stored by Python and can be viewed with help() or documentation tools.
  • Docstrings describe what a function, class, or module does, usually in one clear sentence or short paragraph.

Example: A Simple Docstring

Here, the triple-quoted text directly inside the function becomes its official docstring, which Python can display using help().

docstring_example.py
def greet():
    """Prints a friendly greeting message."""
    print("Hello there!")

greet()
print(greet.__doc__)
Output
Hello there!
Prints a friendly greeting message.

greet.__doc__ shows Python actually stored that triple-quoted text as documentation attached to the function — something a plain # comment could never do.

Why and When to Comment

A common beginner habit is to write comments that simply restate what the code already says, like # add 1 to x above x = x + 1. This adds no value, since anyone reading the code can already see what it does.

Good comments instead explain why a piece of code exists — the reasoning, the edge case being handled, or the business rule being followed — information that is not obvious just from reading the code itself.

Weak Comment (explains WHAT)

  • # add 1 to count
  • count = count + 1

Useful Comment (explains WHY)

  • # Increment count to include the item
  • # we just added to the cart
  • count = count + 1

PEP 8 Comment Style

PEP 8, Python's official style guide, gives specific guidance on comment formatting to keep code consistent across projects and teams.

  • Write comments as complete sentences, starting with a capital letter (unless the first word is a lowercase identifier).
  • Leave at least two spaces before an inline # comment, and one space after the # itself.
  • Keep comments up to date — an outdated comment is worse than no comment at all.
  • Avoid stating the obvious; add value beyond what the code already shows.

Common Mistakes

Avoid These Mistakes
  • Writing comments that just repeat what the code obviously does.
  • Leaving outdated comments that no longer match the actual code.
  • Using the triple-quote trick as a substitute for real docstrings.
  • Over-commenting every single line instead of only where it adds value.
  • Forgetting a space after the # symbol, hurting readability.

Best Practices

  • Comment the "why," not the "what" — the code already shows what it does.
  • Keep comments short, clear, and up to date as code changes.
  • Use docstrings for functions, classes, and modules once you reach those lessons.
  • Follow PEP 8 spacing: one space after #, two spaces before an inline comment.
  • Remove leftover or commented-out debug code before finishing a project.

Frequently Asked Questions

What symbol starts a comment in Python?

The hash symbol (#). Everything after it on that line is ignored by the interpreter.

Does Python have a true multi-line comment symbol?

No. The standard approach is multiple lines each starting with #. Triple-quoted strings are sometimes used informally, but they are technically string literals, not comments.

What is the difference between a comment and a docstring?

A comment (#) is purely for humans reading the source code and is discarded entirely by Python. A docstring is a triple-quoted string as the first line of a function, class, or module that Python actually stores and can display via help() or __doc__.

Should I comment every line of code?

No. Over-commenting adds noise. Comment where the reasoning is not obvious, and let clear code speak for itself elsewhere.

Does PEP 8 require a specific comment style?

PEP 8 recommends complete sentences, a space after #, and keeping comments accurate and current, though it is a style guide rather than a strict requirement enforced by Python itself.

Key Takeaways

  • A single-line comment starts with # and is ignored by Python.
  • Multi-line comments are typically written as several # lines in a row.
  • Triple-quoted text used as a comment is really just an unused string literal.
  • A docstring is a special, stored form of documentation for functions, classes, and modules.
  • Good comments explain why code exists, not just what it does.

Summary

Comments are one of the simplest tools in Python, yet one of the most important for writing code that other people — and future you — can actually understand. The # symbol handles everyday notes, while docstrings provide a more formal, tool-readable form of documentation.

In this lesson, you learned how to write single-line and multi-line comments, what docstrings are, and how to follow PEP 8 guidance for useful, well-styled comments. Next, you will learn about variables — how Python stores and labels data.

Lesson 6 Completed
  • You can write single-line and multi-line comments.
  • You understand the difference between a comment and a docstring.
  • You know to comment the "why," not the "what."
  • You are ready to learn about variables.
Next Lesson →

Variables