Code commenting is a crucial aspect of writing readable and maintainable Python programs. Comments help developers understand the logic behind the code, provide documentation, and make collaboration easier. Python supports two types of comments: single-line comments and multi-line (block) comments.

Single-Line Comments

Single-line comments in Python begin with a # symbol. Everything after # on that line is ignored by the Python interpreter.

# This is a single-line comment
x = 10  # Assigning value 10 to variable x
print(x)  # Printing the value of x

- Use Cases for Single-Line Comments:

  • To explain the purpose of a variable or a line of code;
  • To provide context for a specific operation;
  • To temporarily disable a line of code during debugging;

Multi-Line (Block) Comments

Python does not have built-in support for multi-line comments like other languages (e.g., /* */ in C). However, multi-line comments can be achieved using:

  • Consecutive # symbols on each line;
  • Triple-quoted strings (""" """ or ''' ''');

- Using Consecutive # Symbols

# This is a multi-line comment
# describing the purpose of the following function
# which calculates the sum of two numbers.
def add(a, b):
    return a + b

- Using Triple-Quoted Strings

Triple-quoted strings can be used as multi-line comments, but they are technically docstrings (more on this later). These strings are ignored when not assigned to a variable.

"""
This is a multi-line comment
using triple double-quotes.
It is often used for documentation.
"""
x = 20
print(x)

Docstrings (Documentation Strings)

Docstrings are a special type of comment used to document modules, functions, classes, and methods. Unlike regular comments, docstrings are stored as metadata and can be accessed via the __doc__ attribute.

def multiply(a: int, b: int):
    """
    This function takes two numbers as input
    and returns their product.
    """
    return a * b

print(multiply.__doc__)  # Accessing the docstring

- Docstring Types:

Single-line Docstrings: Used for short descriptions.

def square(x: int):
    """Returns the square of a number."""
    return x * x

- Multi-line Docstrings: Used for detailed explanations.

def divide(a, b):
    """
    Performs division of two numbers.

    Parameters:
    a (int, float): The numerator.
    b (int, float): The denominator.

    Returns:
    float: The result of division.
    """
    return a / b

Best Practices for Code Commenting

- Write Clear and Concise Comments

  • Avoid unnecessary or redundant comments;
  • Explain "why" the code does something, not just "what" it does;
# bad example
x = x + 1  # Increment x by 1

# better example
x += 1 # Increase the counter to track the next iteration

- Use Docstrings for Functions, Classes, and Modules

Docstrings provide documentation and can be accessed programmatically.

- Keep Comments Up-to-Date

Outdated comments can mislead future developers. Update comments when modifying code.

- Avoid Over-Commenting

Too many comments can clutter the code. Focus on commenting only complex logic.

- Use Consistent Formatting

Follow a standard style for comments. For example:

  • Use capital letters at the start;
  • End with a period for full sentences;

- Use Inline Comments Sparingly

Use inline comments (#) only when necessary, and keep them brief.

Automated Documentation Tools

Well-documented Python code can be used with tools like:

  • Sphinx - Generates documentation from docstrings;
  • pydoc - Extracts and displays docstrings;
  • doctest - Allows testing of embedded examples in docstrings;