The Art of Commenting in Python

Comments are helpful notes written inside your code that are completely ignored by the Python interpreter. Their only purpose is to be read by human beings.

Learning how to write clean, clear comments is a vital skill that separates beginning programmers from seasoned professionals. It is the practice of explaining the why behind your code, rather than just the what.

Why Should We Write Comments?

While writing clear code is always the priority, even the cleanest code cannot tell the reader the original thoughts or constraints behind your choices.

• Context and Clarity: Comments explain the purpose of complicated mathematics, specific business rules, or unique workarounds.
• Teamwork: When you write programs with others, comments help your colleagues understand your thought process without needing to ask you directly.
• Future Proofing: The most important person reading your comments is your future self. Several months from now, you will be incredibly grateful for the friendly notes you left behind.
• Isolating Bugs: You can use comments to temporarily turn off lines of code while debugging. This helps you figure out exactly which line is causing a problem.

How to Write Comments in Python

Python gives you several ways to write comments, plus a special style for formal documentation.

Processed Name: Alice Smith
Is Valid Email: True

Docstrings: Documenting Your Functions

A docstring (short for documentation string) is a special kind of comment used to document exactly what a module, class, or function does. It is placed as the very first line inside the function definition and is wrapped in triple quotes ("""...""").

Unlike regular comments, docstrings are not thrown away by Python. They are stored inside the object and can be accessed using Python’s built-in help() function or by reading the special __doc__ attribute.

Let us see an interactive demonstration of this in action:

Common Docstring Formats

When writing professional Python applications, developers follow structured layouts to write docstrings. This allows automated tools to generate complete documentation websites directly from your code comments.

def calculate_tax(income, tax_rate):
    """Calculates the standard income tax.
 
    Args:
        income (float): The total yearly income.
        tax_rate (float): The tax percentage (e.g., 0.15).
 
    Returns:
        float: The calculated tax amount.
    """
    return income * tax_rate

def calculate_tax(income, tax_rate):
    """Calculates the standard income tax.
 
    :param income: The total yearly income.
    :type income: float
    :param tax_rate: The tax percentage (e.g., 0.15).
    :type tax_rate: float
    :returns: The calculated tax amount.
    :rtype: float
    """
    return income * tax_rate

def calculate_tax(income, tax_rate):
    """
    Calculates the standard income tax.
 
    Parameters
    ----------
    income : float
        The total yearly income.
    tax_rate : float
        The tax percentage (e.g., 0.15).
 
    Returns
    -------
    float
        The calculated tax amount.
    """
    return income * tax_rate

Best Practices for Commenting

1. Keep Comments Updated: A comment that is outdated and wrong is far worse than no comment at all! If you edit your code, make sure to update your comments as well.

2. Comment the Why, Not the What: Your code should explain what is happening. Your comments should explain why it is happening.

   Bad: x = x + 1 # Add one to x (This is completely obvious from the code itself!)

   Good: x = x + 1 # Offset by one to adjust for the zero-based index. (This explains the logical reason!)

3. Use Self-Documenting Names: The best comment is often just choosing a beautiful name for a variable or function.

   Bad: d = 5 # d is the number of days

   Good: days_since_last_login = 5 (The variable name is so clear it explains itself!)