Python Comments: Single-Line, Multi-Line & Docstrings

Python Comments and Their Types

Python comments are essential for writing clean, readable, and maintainable code. This guide covers single-line comments, multi-line comments, inline comments, block comments, and docstrings. Learn how to use comments effectively to improve readability and collaboration in your projects.

By the end, you will know how to comment multiple lines, create Docstrings for functions and classes, and follow PEP 8 guidelines for Python comments.

What Are Comments in Python?

• In Python coding, comments are non-executable lines of text that explain code logic, document functions, or temporarily disable code.
• A comment serves as a note or reminder, ignored by the Python interpreter.
• Comments start with the hash symbol (#) and Docstrings with triple quotes (""" or ''').
• They help developers understand complex logic, making maintenance easier, especially in team projects.

Example of a Basic Comment

# This statement prints hello world
print("Hello, World!")

Types of Comments in Python

There are three main types of comments to cover various coding needs:

1. Single-Line or Inline Comments
2. Block Comments
3. Multi-Line Comments or Docstrings

1. Single-Line or Inline Comments

Single-line comments in Python use the # symbol and span only one line. They are ideal for quick explanations of statements or commenting out code. Place inline comments after code with at least two spaces before the #.

• Use for brief explanations or annotations.
• Keep comments clear and concise.
• Ideal for quick notes or disabling code lines.
• Place inline comments after code on the same line.
• Use sparingly to avoid cluttering the code.
• Helps clarify complex or tricky code parts.

# Calculate the sum of two numbers
total = 5 + 10

print("Sum:", 5 + 10)  # Displays the sum

# print("This won't run")
print("This will run")

2. Python Block Comments

A block comment in Python is a group of consecutive single-line comments, each beginning with # symbol. They are used for longer explanations spanning several lines, often to describe code sections or algorithms.

Block comments work for internal notes and longer explanations.

Use Docstrings for public API documentation.

• Use consecutive # lines for detailed explanations.
• Separate paragraphs with a blank # line.
• Indent to match the related code block.
• Ideal for documenting code sections or complex logic.
• Helps maintain clarity without using docstrings.

# This block comment explains the function
# It calculates the area of a rectangle
# Parameters: length and width
def calculate_area(length, width):
	return length * width

# This block comment shows how to separate paragraphs
# using a blank '#' line for better readability
#
# Each paragraph is distinct, making comments easier
# to scan and understand in complex code sections

3. Multi-Line Comments or Python Docstrings

Multi-line comments in Python, also known as docstrings, use triple quotes (""" or '''). They are perfect for detailed documentation, especially for functions, classes, and modules.

Common Python Docstring formats include Google, NumPy, and reStructuredText (reST).

• Include parameters, return values, and exceptions.
• Provide usage examples within docstrings.
• Accessible via help() and documentation tools like Sphinx.
• Follow PEP 257 for style and conventions.

def factorial(n):
    """
    Compute factorial of n recursively.

    Args:
        n (int): Number to calculate factorial for.

    Returns:
        int: Factorial of n.

    Example:
        >>> factorial(5)
        120
    """
    if n == 0:
        return 1
    return n * factorial(n - 1)

Importance of Comments in Python

A comment bridge the gap between code and human understanding, making Python code blocks more collaborative, easy to maintain, and efficient.

Why Use Comments?

• Clarity: Explain complex logic for easier maintenance.
• Documentation: Docstrings serve as built-in docs.
• Debugging: Temporarily disable code with comments.
• Collaboration: Help teams understand intent.

When to Add Comments

• For complex algorithms or conditional logic.
• Mark TODOs or highlight dependencies.
• Use docstrings for functions and classes.
• Focus on why, not what. Skip obvious comments.

Best Practices for Python Comments and Docstrings

Follow these tips to write effective Python comments and Docstrings that align with PEP 8 and PEP 257 standards.

• Be concise and relevant
• Update comments when code changes
• Use consistent style
• Limit line length to 72 characters
• Generate docs with tools like Sphinx from docstrings