Python Comments

Comprehensive Guide to Python Comments

When writing Python code, comments are an essential tool to enhance readability, maintainability, and understanding. Comments are not executed by the Python interpreter and serve as notes for developers to explain or clarify the purpose of specific code blocks.

Types of Comments in Python

• Single-line Comments
• Multi-line Comments
• Docstrings (Documentation Strings)

❉ Single-line Comments

A single-line comment begins with the # symbol. Anything written after the # is ignored by the Python interpreter.

Example:

  # This is a single-line comment
print("Hello, World!")  # This prints a greeting message
  📋 copy code

Output

Explanation:

• The first line is a single-line comment explaining the code.
• The inline comment next to the print function describes its purpose.

❉ Multi-line Comments

Python does not have a specific syntax for multi-line comments. However, developers commonly use multiple single-line comments or docstrings for this purpose.

Using Consecutive Single-line Comments

  # This is a multi-line comment
# written using single-line comment syntax.
# It explains the following block of code.
name = "Alice"
print("Hello,", name)
  📋 copy code

Output

Using Triple-quoted Strings

Although triple-quoted strings (''' or """) are generally used for docstrings, they can be employed to create multi-line comments since they are ignored if not assigned to a variable or used as a docstring.

  '''
This is another way to write multi-line comments.
These are not strictly comments but ignored strings.
'''
print("Python is fun!")
  📋 copy code

Output

Note: Triple-quoted strings are better used for docstrings.

❉ Docstrings (Documentation Strings)

Docstrings are a special type of comment used to describe the purpose of a function, class, or module. These are enclosed within triple quotes (''' or """) and can span multiple lines. Unlike regular comments, docstrings are accessible during runtime using the __doc__ attribute.

Example with Function Docstring

  def greet(name):
    """
    This function greets the person whose name is passed as an argument.
    It takes one parameter:
    - name: A string containing the person's name.
    """
    return f"Hello, {name}!"

print(greet("Alice"))
print(greet.__doc__)  # Accessing the docstring
  📋 copy code

Output

Explanation:
The docstring provides detailed information about the function, which can be retrieved programmatically.

❉ Best Practices for Writing Comments

• Be Concise but Clear:
  Write comments that are brief but descriptive enough to explain the purpose of the code.
• Avoid Redundant Comments:
  Do not write comments that simply repeat the code. For example: x = 5 # Assign 5 to x # Avoid this type of comment
• Use Docstrings for Documentation:
  Use docstrings for explaining modules, classes, and functions.
• Update Comments as Code Changes:
  Outdated comments can lead to confusion, so always update them when modifying the code.
• Follow Style Guides:
  Adhere to the style guides like PEP 8 for Python to maintain consistency.

❉ Comprehensive Code Example

Here’s a complete Python program demonstrating various types of comments:

  # Import necessary library
import math  # Importing math for advanced mathematical calculations

def calculate_circle_area(radius):
    """
    This function calculates the area of a circle given its radius.
    
    Formula used:
    area = π * r^2
    
    Parameters:
    - radius (float): The radius of the circle
    
    Returns:
    - float: The area of the circle
    """
    # Calculate the area
    area = math.pi * (radius ** 2)  # π * r^2
    return area

# Main program
if __name__ == "__main__":
    # Prompt user for input
    radius = float(input("Enter the radius of the circle: "))  # Get radius from user
    
    # Calculate area
    area = calculate_circle_area(radius)
    
    # Display result
    print(f"The area of the circle with radius {radius} is: {area:.2f}")
  📋 copy code

Sample Output:

Input Output

Explanation

• The single-line comment clarifies the purpose of each step in the code.
• The docstring in the function documents its purpose, parameters, and return value.
• Inline comments explain specific lines of logic.

❉ Shortcut Keys for Comments

In most Python development environments, such as VSCode, PyCharm, or IDLE, you can quickly comment and uncomment lines of code using the following shortcut keys.

Comment a single line or selected block of lines:

• Windows/Linux: Ctrl + /

• Mac: Cmd + /

This will insert a # symbol at the beginning of the selected lines, effectively commenting them out. If the lines are already commented, pressing the shortcut again will uncomment them.

Comment a block of code (multi-line comments) in some editors (e.g., VSCode, PyCharm):

• Windows/Linux: Shift + Alt + A

• Mac: Shift + Option + A

This will wrap the selected code with ''' or """, turning it into a multi-line comment (often used for docstrings in Python).

❉ Conclusion

Comments are vital for writing maintainable and readable code. They help developers understand the purpose and functionality of the code, especially when revisiting it after a long time or collaborating with others. By leveraging comments effectively, you can make your code more professional and user-friendly.