Python - Chapter 2: Comments

Python – Chapter 2: Comments

Comments are a very important part of code; they are used to explain the purpose of the code, helping others or oneself to understand the logic of the code in the future. In Python, comments are not executed by the Python interpreter; they are merely auxiliary information for programmers to read and understand the code.

1. Single-line Comments

In Python, single-line comments start with a hash symbol #, and everything after the hash symbol is considered a comment. Python ignores this content.

Example:

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

• # The text after the hash symbol is a comment that explains the purpose of the current code or adds additional information.
• Comments can be placed before the code or after the code on the same line.

2. Multi-line Comments

Python does not have a dedicated syntax for multi-line comments, but you can use multiple # symbols to comment multiple lines. There is also a way to use triple quotes (''' or """) to achieve this.

Method 1: Using multiple `#` to comment multiple lines

# This is the first line of a multi-line comment
# This is the second line of a multi-line comment
# This is the third line of a multi-line comment

Method 2: Using triple quotes for comments

'''
This is the first line of a multi-line comment
This is the second line of a multi-line comment
This is the third line of a multi-line comment
'''

Or:

"""
This is the first line of a multi-line comment
This is the second line of a multi-line comment
This is the third line of a multi-line comment
"""

Although triple quotes are typically used for docstrings, they can also be used as multi-line comments. Note that when using triple quotes, they are also recognized by the Python interpreter as strings, but if not assigned to a variable, they will not be executed.

3. Docstrings

Docstrings are typically used to provide documentation for modules, classes, methods, or functions. It is a special form of multi-line comment. Usually, docstrings are enclosed in triple quotes (either single or double quotes) and are located at the beginning of a function or class.

Example:

def greet(name):
    """
    This function takes a name and prints a greeting.
    
    Parameters:
    name (str): The name of the person
    
    Returns:
    None
    """
    print(f"Hello, {name}!")

• Purpose: Docstrings are mainly used for automatically generating documentation and help information.
• Usage: You can view a function’s docstring using the help() function.

help(greet)  # Displays the docstring for the greet function

4. Best Practices for Comments

• Concise and Clear: Comments should be brief and to the point, avoiding unnecessary verbosity.
• Avoid Excessive Comments: If the code itself clearly expresses the intent, then excessive comments are unnecessary. Comments should typically supplement explanations rather than repeat the code.
• Update Comments: When modifying code, also update comments promptly to avoid outdated or misleading comments.

Example:

# Good comment
# Calculate the square of a number
def square(x):
    return x * x

# Bad comment
# Multiply x and y
def multiply(x, y):
    return x * y

In the latter example, the comment does not add any extra information because the code is already very clear. Avoiding writing obvious comments is a good practice in programming.

Conclusion

• Single-line Comments: Use #, suitable for simple explanations and after code.
• Multi-line Comments: Use multiple # or triple quotes ''' or """.
• Docstrings: Provide detailed descriptions for functions, classes, modules, etc., using triple quotes, typically located above the function or class definition.

Understanding and correctly using comments can greatly enhance the readability and maintainability of code, especially in collaborative development environments.

Python – Chapter 2: Comments