Learn How to Write Comments in Python: Absolute Beginners Tutorial

Comments are lines that Python ignores entirely when it runs your program. They exist for people — to explain what code does, why a decision was made, or to temporarily disable a line during debugging. Learning to write comments well is one of the first habits that separates readable code from code that confuses everyone, including the person who wrote it six months later.

Python's comment syntax is intentionally minimal. There is one comment character — the hash symbol (#) — and it applies to everything from that point to the end of the line. That simplicity makes comments easy to learn but easy to misuse. This tutorial covers single-line comments, inline comments, block comments, and docstrings, along with the PEP 8 style guidelines that govern when and how to use each one.

What Is a Comment in Python?

A comment is any text in a Python source file that begins with the # character, excluding # characters that appear inside string literals. When the Python interpreter reads a file, it discards everything on a line from the # onward before any execution takes place. The comment text never becomes part of the compiled bytecode.

The practical consequence is straightforward: comments carry zero runtime cost and produce no side effects. They exist purely in source code for human readers. This makes them the right place for intent, context, and warnings — information that does not belong in the logic itself.

# This entire line is a comment — Python ignores it completely
print("Hello")        # Only the text after # is a comment here

tag = "#python"       # The # inside the string is NOT a comment
hashtag = '#' + 'py'  # Also not a comment — it is inside a string

Types of Comments in Python

Python has one comment character but several patterns of use. Each pattern serves a different purpose, and choosing the right one keeps your code readable without adding clutter.

Single-Line Comments

A single-line comment occupies its own line, placed above the code it describes. This is the standard way to explain what a block of logic does or why a particular approach was chosen. PEP 8 recommends starting comment text with a capital letter and writing in complete sentences where practical.

# Calculate the area of a rectangle
width = 10
height = 5
area = width * height

# Using integer division to avoid floats in the result
pages = total_words // words_per_page

Inline Comments

An inline comment sits at the end of a line of code. PEP 8 requires at least two spaces between the statement and the #, and one space after the #. Inline comments should be used sparingly. When the code is self-explanatory, an inline comment just creates noise.

MAX_RETRIES = 3        # Network requests only — not for file I/O
timeout = 30          # Seconds before connection is dropped
x = x + 1            # Good: non-obvious increment reason goes here
y = y + 1            # Bad: no information added — remove this one

Block Comments (Multi-Line)

Python has no dedicated multi-line comment syntax. When you need to write a longer explanation that spans multiple lines, the standard approach is to put a # at the start of each line. Each line in a block comment should be indented to match the code it sits above.

# Validate the user-supplied email address before sending a
# confirmation link. The regex below follows RFC 5322 loosely;
# it catches the most common formatting errors without being
# brittle against edge-case valid addresses.
import re

def is_valid_email(address):
    pattern = r'^[^@\s]+@[^@\s]+\.[^@\s]+$'
    return bool(re.match(pattern, address))

Docstrings vs. Comments

Docstrings are often confused with comments, but they are fundamentally different. A docstring is a string literal — enclosed in triple quotes — placed as the first statement inside a function, class, method, or module. Because it is a string, not a comment, Python stores it on the object's __doc__ attribute at runtime. IDEs, the built-in help() function, and documentation generators like Sphinx all read it from there.

Comments, by contrast, are stripped out before the code ever runs. They cannot be read programmatically. The practical rule is simple: use docstrings to document the interface of something (what it accepts, what it returns, what it does), and use comments to explain the internal reasoning of the implementation.

def celsius_to_fahrenheit(celsius):
    """Convert a Celsius temperature to Fahrenheit.

    Args:
        celsius (float): Temperature in degrees Celsius.

    Returns:
        float: Equivalent temperature in degrees Fahrenheit.
    """
    # Multiply first, then add — avoids a separate variable
    return (celsius * 9 / 5) + 32

# Access the docstring at runtime
print(celsius_to_fahrenheit.__doc__)

"Code is read much more often than it is written." — Guido van Rossum

Python Comments: Key Takeaways

1. Python uses # as its only comment character. Everything after # on a line is ignored by the interpreter — unless the # appears inside a string literal.
2. There are three common comment patterns: single-line (above a block), inline (end of a statement), and block (multiple consecutive # lines). Python has no dedicated multi-line comment syntax.
3. Docstrings are not comments. They are triple-quoted string literals stored as __doc__ at runtime, used to document functions, classes, and modules. Use comments to explain how; use docstrings to explain what.
4. PEP 8 recommends capitalizing comment text, keeping inline comments sparse, and maintaining indentation parity between comments and the code they describe.
5. Good comments explain intent and non-obvious decisions — not mechanics that the code already makes clear. If a comment just repeats what the code says, it adds noise and should be removed.

Writing clean comments is a habit that compounds. A codebase with accurate, purposeful comments stays navigable as it grows. A codebase with stale or redundant comments becomes actively misleading. The goal is not maximum comment density — it is maximum clarity.