Chapter 4: Python Comments

Understanding Python Comments

Comments in Python are non-executable lines of text used to explain code, making it easier to understand and maintain. They are ignored by the Python interpreter, so they don’t affect how your program runs. Comments are essential for documenting code, especially in collaborative projects or when revisiting code later. This chapter covers single-line and multi-line comments, their syntax, and best practices for effective commenting.

Single-Line Comments

Single-line comments start with the hash symbol (#) and continue until the end of the line. They are ideal for brief explanations or notes:

# This is a single-line comment
print("Hello, World!")  # Prints a greeting
                

In this example, the first line is a standalone comment, and the second comment explains the print statement. The interpreter ignores everything after # on each line.

Multi-Line Comments

Python doesn’t have a specific syntax for multi-line comments, but you can use triple quotes (""" or ''') to create them. Triple quotes are typically used for docstrings (documentation for functions or modules), but they work as comments when not assigned to a variable:

"""
This is a multi-line comment.
It spans multiple lines.
Useful for detailed explanations.
"""
print("Hello, Python!")
                

This outputs Hello, Python!, ignoring the text within triple quotes. Alternatively, you can use multiple single-line comments:

# This is line 1 of the comment
# This is line 2 of the comment
print("Hello, Python!")
                

Using Comments Effectively

Comments should clarify code without stating the obvious. For example, avoid:

# Print hello
print("hello")
                

Instead, explain the purpose or logic:

# Display a welcome message to the user
print("hello")
                

Follow Python’s style guide, PEP 8, which recommends keeping comments concise and placing them above the code they describe or inline for short notes. Avoid over-commenting, as it can clutter code.

Docstrings vs. Comments

While triple quotes can be used for comments, they are more commonly used as docstrings to document functions, classes, or modules. Docstrings are accessible programmatically (e.g., via __doc__):

def greet(name):
    """Return a greeting message for the given name."""
    return f"Hello, {name}!"
print(greet.__doc__)  # Outputs: Return a greeting message for the given name.
                

Unlike regular comments, docstrings are stored and can be retrieved by tools like help() or documentation generators.

Next Steps

With an understanding of comments, move to Chapter 5: Python Variables to learn how to store data in your programs. Use the sticky sidebar to navigate the 50-chapter learning path. For questions, reach out via our Contact page or email info@bloggytech.com. Bloggy Tech, based in Wah Cantt, Pakistan, is here to support your Python learning journey.