How to Comment in Python?

Welcome back! Now that you’ve learned about booleans in Python, let’s move on to another essential topic: comments. Comments are a crucial part of writing clean, understandable code. They help you and others understand what your code does, making it easier to maintain and debug. In this article, we’ll explore how to use comments in Python effectively.

What are Comments?

Comments are lines in your code that are not executed by the Python interpreter. They are intended to provide explanations or notes about your code. Comments can help you remember why you wrote the code in a certain way, explain complex logic, or provide instructions for other developers who might work on the code in the future.

Types of Comments in Python

Python supports two types of comments: single-line comments and multi-line comments.

1. Single-line Comments

Single-line comments start with a hash symbol (#) and extend to the end of the line. Everything after the # is ignored by the Python interpreter.

# This is a single-line comment
print("Hello, World!")  # This comment is next to a line of code

2. Multi-line Comments

Python does not have a specific syntax for multi-line comments. However, you can use multiple single-line comments or triple-quoted strings (which are usually used for docstrings) to create multi-line comments.

Using Multiple Single-line Comments

# This is a multi-line comment
# using multiple single-line comments
# to explain something in detail.
print("Hello, World!")

Using Triple-quoted Strings

Although triple-quoted strings are primarily used for docstrings (which we’ll discuss shortly), they can also be used as multi-line comments. Note that this is more of a convention rather than a standard practice for comments.

"""
This is a multi-line comment
using triple-quoted strings.
It can span multiple lines.
"""
print("Hello, World!")

Docstrings

Docstrings are a special kind of comment used to document modules, classes, functions, and methods. They are written using triple-quoted strings (''' or """) and are placed as the first statement in a module, class, function, or method. Docstrings are accessible through the __doc__ attribute and can be used by documentation tools.

Module Docstring

"""
This module provides functions to perform basic arithmetic operations.
"""

def add(a, b):
    """
    Add two numbers and return the result.
    """
    return a + b

Class Docstring

class Calculator:
    """
    A simple calculator class to perform basic arithmetic operations.
    """

    def add(self, a, b):
        """
        Add two numbers and return the result.
        """
        return a + b

Function Docstring

def subtract(a, b):
    """
    Subtract the second number from the first number and return the result.
    """
    return a - b

Best Practices for Writing Comments

1. Be Clear and Concise: Comments should be easy to read and understand. Avoid writing overly long comments.
2. Keep Comments Up-to-date: Ensure your comments reflect the current state of the code. Outdated comments can be misleading.
3. Avoid Obvious Comments: Don’t state the obvious. Comments should provide additional information that is not immediately clear from the code itself.

# Bad comment: This is obvious from the code
x = 5  # Set x to 5

# Good comment: Explains why this value is used
x = 5  # Initialize x to 5 because it represents the starting count

4. Use Comments to Explain Why, Not What: Instead of explaining what the code does (which should be clear from the code itself), explain why you made certain decisions.

# Bad comment: Explains what the code does
total = price * quantity  # Multiply price by quantity

# Good comment: Explains why this calculation is done
# Calculate the total cost to be used for the invoice
total = price * quantity

5. Use Docstrings for Documentation: Use docstrings to document modules, classes, and functions. This helps generate external documentation and provides a reference for other developers.

Example: Adding Comments to a Program

Let’s see an example of a Python program with comments and docstrings.

"""
This module provides functions to calculate the area of different shapes.
"""

def area_of_circle(radius):
    """
    Calculate the area of a circle given its radius.

    :param radius: The radius of the circle
    :return: The area of the circle
    """
    import math
    return math.pi * radius ** 2

def area_of_rectangle(width, height):
    """
    Calculate the area of a rectangle given its width and height.

    :param width: The width of the rectangle
    :param height: The height of the rectangle
    :return: The area of the rectangle
    """
    return width * height

# Example usage
radius = 5
circle_area = area_of_circle(radius)
print(f"The area of the circle with radius {radius} is {circle_area}")

width = 10
height = 5
rectangle_area = area_of_rectangle(width, height)
print(f"The area of the rectangle with width {width} and height {height} is {rectangle_area}")

In this example, we use docstrings to document the module and functions. We also add comments to explain the purpose of variables and calculations.

Conclusion

Comments are an essential part of writing clear and maintainable code. They help you and others understand the purpose and logic of your code. In Python, you can use single-line comments, multi-line comments, and docstrings to document your code effectively. By following best practices for writing comments, you can make your code more readable and easier to maintain.

In our next tutorial, we’ll explore functions in Python and how they can help you organize and reuse your code. Stay tuned, and happy coding!