Comments and Docstrings in Python – A Beginner’s Guide

Comments and Docstrings in Python

1. Introduction

Understanding comments and docstrings in Python is essential for writing clean, readable, and well-documented code. Comments help explain the logic behind the code, while docstrings provide structured documentation for functions, classes, and modules.

In this guide, we will explore how to use comments and docstrings in Python, real-life applications, common mistakes, and how to fix them.

Focus Keyphrase: Comments and Docstrings in Python

2. What are Comments in Python?

Comments are lines of text that Python ignores during execution. They help developers understand the code but do not affect the program’s functionality.

Single-Line Comments (#)

Use # to write a single-line comment.

# This is a comment
print("Hello, World!")  # This prints a message

Multi-Line Comments (Using #)

For multiple lines, use # at the beginning of each line.

# This is a multi-line comment
# It describes the purpose of the next code block
print("Python is fun!")

3. What are Docstrings in Python?

Docstrings (documentation strings) provide a structured explanation of a function, class, or module. Unlike comments, docstrings are stored in memory and can be accessed using __doc__.

Single-Line Docstring

Use triple quotes (""" """ or ''' ''') inside a function to describe what it does.

def greet():
    """This function prints a greeting message."""
    print("Hello, Python!")

Multi-Line Docstring

Used for detailed explanations.

def add_numbers(a, b):
    """
    This function takes two numbers as input,
    adds them, and returns the result.
    """
    return a + b

Accessing Docstrings:

print(add_numbers.__doc__)

Output:

This function takes two numbers as input,
adds them, and returns the result.

4. Real-Life Applications of Comments and Docstrings

a) Explaining Complex Code

# This function calculates the area of a circle
def circle_area(radius):
    """Returns the area of a circle given the radius."""
    return 3.1416 * radius ** 2

b) API Documentation

Docstrings help create automatic documentation for functions and classes.

class Car:
    """
    A class to represent a car.
    
    Attributes:
    make (str): The brand of the car.
    model (str): The model of the car.
    """

    def __init__(self, make, model):
        self.make = make
        self.model = model

c) Debugging and Collaboration

Well-commented code helps teams understand and debug code efficiently.

5. Common Mistakes and How to Fix Them

Mistake 1: Using Comments Instead of Docstrings

❌ Incorrect:

def multiply(a, b):
    # This function multiplies two numbers
    return a * b

✅ Fix: Use a docstring for documentation.

def multiply(a, b):
    """This function multiplies two numbers and returns the result."""
    return a * b

Mistake 2: Writing Unnecessary Comments

❌ Incorrect:

x = 10  # Assigning 10 to x
y = 20  # Assigning 20 to y
z = x + y  # Adding x and y

✅ Fix: Comments should explain why something is done, not what is obvious.

# Calculate the total cost after adding tax
total_cost = price + (price * tax_rate)

Mistake 3: Forgetting to Close Multi-Line Docstrings

❌ Incorrect:

def example():
    """This is a function without closing docstring
    print("Hello")

✅ Fix: Always close the docstring properly.

def example():
    """This function prints a greeting message."""
    print("Hello")

6. Conclusion

Therefore, Mastering comments and docstrings in Python helps developers write readable, maintainable, and well-documented code. Use # for simple comments and """ """ for detailed function and class documentation. Proper documentation makes collaboration easier and improves code quality.

Next Steps:

  • Start using docstrings in your functions and classes.
  • Use comments only when necessary to explain complex logic.
  • Practice writing clean and well-documented Python scripts.
previous
next
Scroll to Top