Smart Commenting: The Art of Explanation

# ❌ BAD: Complex logic with explanatory comments
# Check if user is over 18 and has active subscription
if u.age > 18 and u.status == 'active' and u.balance > 0:
    process_order()

# ✅ GOOD: Self-documenting code (No comments needed!)
def is_eligible_for_purchase(user):
    return (
        user.is_adult 
        and user.has_active_subscription 
        and user.has_positive_balance
    )

if is_eligible_for_purchase(user):
    process_order()

def connect_to_database(url: str, retries: int = 3) -> bool:
    """
    Establishes a secure connection to the primary database replica.

    Backs off exponentially if the connection fails, up to the specified
    number of retries. Uses SSL by default.

    Args:
        url (str): The JDBC or ODBC connection string.
            Example: 'postgresql://user:pass@localhost:5432/db'
        retries (int, optional): Max connection attempts before giving up. 
            Defaults to 3.

    Returns:
        bool: True if connection successful, False if all retries failed.

    Raises:
        ConnectionTimeout error: If the server is reachable but unresponsive.
        ValueError: If the URL format is invalid.
    """
    # Implementation hidden...
    return True

def calculate_tax(amount):
    # TODO: Switch to external TaxJar API for international support
    rate = 0.20
    
    # FIXME: This crashes if amount is negative!
    # HACK: Use abs() for now until validation is fixed upstream
    return abs(amount) * rate

    # OPTIMIZE: This nested loop is O(n^2), refactor to use a hash map
    for item in items:
        # ...

# ❌ LEGACY (Pre-2015): Using comments (Fragile)
def greet(name):
    # type: (str) -> str
    return "Hi " + name

# ✅ MODERN (Recommended): Using Type Hints (Robust)
def greet(name: str) -> str:
    return f"Hi {name}"