In Python, annotations are used to provide additional information about various elements in your code, such as function parameters, return values, and variables. Annotations are not enforced by the Python interpreter itself, but they can be useful for documentation, type hinting, and code analysis tools. Annotations can be added as single-line comments or multi-line docstrings.
1. Single Line Annotations.
Single-line annotations are typically added using a single-line comment (prefixed with `#`). They are often used for providing a brief description or explanation of the code. Single-line annotations are not directly tied to function parameters or return values but can be used to provide context to the reader.
Example: In the below example, the comment serves as a single-line annotation providing an explanation of what the function does.
def calculate_discount(price: float, discount_rate: float) -> float:
# Calculate the discounted price based on the given price and discount rate
discounted_price = price * (1 - discount_rate)
return discounted_price
2. Multi-Line Annotations (Docstrings).
Multi-line annotations are often referred to as “docstrings” in Python. They are enclosed in triple quotes (`”’` or `“””`) and are used to provide detailed documentation about functions, classes, modules, or methods.
Docstrings are more formal and can be used for automatic documentation generation and type hinting using tools like Sphinx and IDEs that support code introspection.
There are three types of multi-line annotations: one-line, multi-line, and multi-line with a summary line.
2.1 One-Line Docstring.
A one-line docstring provides a brief summary of the function’s purpose in a single line. It’s placed immediately after the function signature.
Example:
def calculate_discount(price: float, discount_rate: float) -> float:
"""Calculate the discounted price."""
discounted_price = price * (1 - discount_rate)
return discounted_price
2.2 Multi-Line Docstring.
A multi-line docstring provides more detailed information about the function, including its parameters, return value, and any additional information. It’s typically used when more explanation is required.
Example:
def calculate_discount(price: float, discount_rate: float) -> float:
"""
Calculate the discounted price.
Args:
price (float): The original price of the product.
discount_rate (float): The discount rate as a decimal.
Returns:
float: The calculated discounted price.
"""
discounted_price = price * (1 - discount_rate)
return discounted_price
2.3 Multi-Line Docstring with Summary Line.
This format includes a summary line followed by a more detailed explanation. It’s often used to provide a quick overview of the function’s purpose.
Example:
def calculate_discount(price: float, discount_rate: float) -> float:
"""
Calculate the discounted price.
This function takes the original price of a product and a discount rate,
and calculates the discounted price after applying the discount rate.
Args:
price (float): The original price of the product.
discount_rate (float): The discount rate as a decimal.
Returns:
float: The calculated discounted price.
"""
discounted_price = price * (1 - discount_rate)
return discounted_price
3. Conclusion.
In summary, annotations in Python, whether as single-line comments or multi-line docstrings, help provide context, documentation, and type hinting for your code. Choosing the appropriate style and level of detail depends on the complexity of your code and the audience you’re targeting.
