Introduction to Python Comments

Comments are used to add explanations or notes to your code without affecting its execution. The Python interpreter ignores comments, focusing only on the actual code. This makes comments an invaluable tool for explaining complex formulas, algorithms, and business logic.

Python supports three main types of comments:

1. Block Comments
2. Inline Comments
3. Documentation Strings (Docstrings)

1. Block Comments

Block comments are used to describe a section of code that follows them. These comments are typically indented at the same level as the code block they describe.

To create a block comment, start with a single hash sign (#), followed by a space and the comment text. For example:

# Increase price by 5%
price = price * 1.05

2. Inline Comments

Inline comments are placed on the same line as the code they describe. Similar to block comments, inline comments begin with a hash sign (#), followed by a space and the comment text.

Here's an example of an inline comment:

salary = salary * 1.02   # Increase salary by 2%

3. Python Docstrings

Docstrings, short for documentation strings, are special types of comments that serve as documentation for modules, classes, and functions. Unlike regular comments, docstrings can be accessed at runtime using the obj.__doc__ attribute, where obj is the name of the function or object.

Docstrings are technically not comments—they create anonymous variables that reference the strings and are not ignored by the interpreter. However, they are widely used for documenting code.

Types of Docstrings

Python provides two types of docstrings: one-line docstrings and multi-line docstrings.

One-Line Docstrings

As the name suggests, a one-line docstring is a single line of text enclosed within triple quotes ("""). It should start and end with triple quotes, and there should be no blank lines before or after it.

Example of a one-line docstring:

def quicksort():
    """Sort the list using the quicksort algorithm"""
    ...

Multi-Line Docstrings

Multi-line docstrings span multiple lines and are used to provide detailed documentation for more complex code. They also start and end with triple quotes (""").

Example of a multi-line docstring:

def increase(salary, percentage, rating):
    """Increase salary based on rating and percentage.
    
    rating 1 - 2: no increase
    rating 3 - 4: increase 5%
    rating 4 - 6: increase 10%
    """

Python Multiline Comments

Python does not support multiline comments natively. However, you can use multi-line docstrings as a workaround for adding comments that span multiple lines. This practice was even recommended by Guido van Rossum, the creator of Python.

Best Practices for Comments

• Keep comments clear, concise, and explanatory.
• Use block comments for sections of code and inline comments for specific lines.
• Use docstrings to document functions, classes, and modules.
• Avoid over-commenting; code should be self-explanatory whenever possible.

Summary

• Use comments to document your code when necessary.
• Block comments and inline comments start with a hash sign (#).
• Use docstrings (""") for documenting functions, modules, and classes.