Comment & Documentation

In this lesson, we explore comments and how to create documentation for Python programs. Comments help explain code, while documentation provides detailed instructions for users and developers.

Python Comments

A comment is a part of the code that the interpreter ignores. It is used to explain code or temporarily disable certain lines during testing.

Single-Line Comments

Use # to create single-line comments:

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

Output:

Hello, World!

Single-Line Comments in Practice

print("Hello, World!")  # Printing Hello, World

Output:

Hello, World!

Disabling Code with Comments

print("Python Program")
# print("This line is disabled")

Output:

Python Program

Multi-Line Comments

To create multi-line comments, use # at the start of each line or use multi-line strings.

Using # for Multi-Line Comments

# This is a multi-line comment
# explaining a block of code.
x = 10
y = 20
print(x + y)

Output:

30

Using Multi-Line Strings

Multi-line strings enclosed in triple quotes can also serve as comments:

"""This is a multi-line comment
explaining a block of code."""
x = 10
y = 20
print(x + y)

Output:

30

Documentation

Python provides ways to add documentation to your programs, making them easier to understand and use.

Docstrings

Docstrings are special strings used to document a Python module, class, function, or method. They are enclosed in triple quotes (""" or ''') and appear as the first statement inside the respective block.

Example: Documenting a Function

def greet(name):
    """This function greets a person with the given name."""
    return f"Hello, {name}!"

print(greet("Alice"))

Output:

Hello, Alice!

Accessing Docstrings

You can access a function's docstring using the __doc__ attribute:

print(greet.__doc__)

Output:

This function greets a person with the given name.

Example: Documenting a Class

class Calculator:
    """This class performs basic mathematical operations."""

    def add(self, a, b):
        """Returns the sum of a and b."""
        return a + b

calc = Calculator()
print(calc.add(5, 3))
print(Calculator.__doc__)

Output:

8
This class performs basic mathematical operations.

Module Documentation

Add a docstring at the beginning of a Python file to describe the module:

"""This module provides utility functions for string manipulation."""

def reverse_string(s):
    return s[::-1]

"""This script calculates the factorial of a given number."""

def factorial(n):
    """Calculates the factorial of n using recursion."""
    if n == 0 or n == 1:
        return 1
    return n * factorial(n - 1)

# Input from the user
num = int(input("Enter a number: "))
# Calculating the factorial
result = factorial(num)
# Printing the result
print(f"The factorial of {num} is {result}.")

With these tools, you can write Python programs that are not only functional but also easy to understand and maintain. Let’s move to the next topic!