Python Comments

Python Comments & Docstrings: Documenting Intent

Clean code is self-documenting, but comments explain why complex decisions were made, while docstrings document public module, class, and function interfaces for developer tooling.

Comment Types in Python

flowchart TD
    A["Documentation Types"] --> B["Inline/Block Comments (#)"]
    A --> C["Docstrings ("""...""")"]
    B --> D["Internal Developer Implementation Notes"]
    C --> E["API Specification & IDE Hover Tooltips"]

Types of Documentation

1. Inline Comments (#): Used sparingly for non-obvious line-level implementation logic.
2. Docstrings ("""..."""): Placed directly underneath function, class, or module definitions. Docstrings are accessible at runtime via object.__doc__ or help().

Practical Code Example

from typing import Optional

def calculate_discounted_price(price: float, discount_percent: float) -> float:
    """Calculate total price after applying a percentage discount.

    Args:
        price: Base price of the product (must be >= 0).
        discount_percent: Discount percentage between 0.0 and 100.0.

    Returns:
        Final calculated price rounded to 2 decimal places.

    Raises:
        ValueError: If price or discount percentage are out of valid range.
    """
    if price < 0 or not (0 <= discount_percent <= 100):
        raise ValueError("Invalid price or discount percentage parameters.")

    # Apply standard percentage discount formula
    discount_amount = price * (discount_percent / 100.0)
    final_price = price - discount_amount
    
    return round(final_price, 2)

if __name__ == "__main__":
    # Test discount calculation logic
    total = calculate_discounted_price(199.99, 15.0)
    print(f"Final Price: ${total}")
    print("Function Docstring Summary:
", calculate_discounted_price.__doc__)

Best Practices & Gotchas

• Do Not Restate the Code: Avoid useless comments like # Increment x by 1 when x += 1 is obvious.
• Use Triple-Quotes for Docstrings: Always use """Triple Quotes""" for docstrings rather than # block comments.
• Maintain Sync: Outdated docstrings are worse than no documentation; update docstrings whenever function parameters or return behavior change.

Self-Check Challenge

Write a function calculate_bmi(weight_kg: float, height_m: float) -> float complete with a Google-style docstring explaining parameters, return value, and exceptions.