In Python, Comments are non-executable statements used to explain what the code is doing. They are ignored by the Python interpreter during execution, making them purely for the benefit of developers reading the source code.

Properly commenting code is a hallmark of professional programming, as it transforms a cryptic script into a maintainable project.

1. Types of Comments in Python

A. Single-Line Comments

The most common type of comment. Anything following the hash symbol (#) on a line is ignored.

• Usage: Used for brief explanations or to temporarily disable a line of code.

• Placement: Can be on its own line or at the end of a statement (inline).

# This is a standalone single-line comment
print("Hello World")  # This is an inline comment

B. Multi-Line Comments

Python doesn't have a specific "block comment" syntax like /* ... */ in C++ or Java. Instead, developers use two main approaches:

1. Consecutive Hash Tags: The PEP 8 style guide recommends using multiple single-line comments for blocks.

2. String Literals: While technically strings, triple-quotes (''' or """) are often used as multi-line comments because if they aren't assigned to a variable, Python simply ignores them.

# Approach 1: PEP 8 Recommended
# This is a multi-line comment
# created using multiple hash symbols.
# Each line is independent.

"""
Approach 2: Triple Quotes
This is often used for longer explanations
or to comment out large chunks of code
during testing/debugging.
"""

C. Docstrings (Documentation Strings)

Docstrings are a special type of comment used to describe the purpose of a module, function, class, or method. They must be the first statement inside the object they describe.

• Unlike regular comments, docstrings can be accessed at runtime using the __doc__ attribute.

def calculate_area(radius):
    """
    Calculates the area of a circle.
    Args:
        radius (float): The radius of the circle.
    Returns:
        float: The calculated area.
    """
    return 3.14159 * (radius ** 2)

print(calculate_area.__doc__)

2. Why Use Comments?

3. Best Practices (PEP 8 Guidelines)

• Keep them up to date: A comment that contradicts the code is worse than no comment at all.

• Don't over-comment: Avoid stating the obvious (e.g., x = 5 # Assign 5 to x is redundant).

• Use complete sentences: Start with a capital letter and end with a period unless it's a short identifier.

• Inline space: Ensure there are at least two spaces between the code and the # symbol.