# Bad: Commenting the obvious
def calculate_total(items):
    total = 0
    for item in items:  # Loop through each item
        total += item.price  # Add price to total
    return total  # Return the total

# Good: Explaining the business logic
def calculate_total(items):
    """Calculate total with tax-exempt status for educational materials."""
    total = 0
    for item in items:
        # Educational materials are tax-exempt in our jurisdiction
        if item.category == 'educational':
            total += item.price
        else:
            total += item.price * 1.08  # 8% sales tax
    return total

# Bad: Explaining what the code does
def process_user_data(user_data):
    # Convert string to lowercase
    user_data = user_data.lower()
    # Remove whitespace
    user_data = user_data.strip()
    # Replace spaces with underscores
    user_data = user_data.replace(' ', '_')
    return user_data

# Good: Explaining why we're doing it
def process_user_data(user_data):
    """Normalize user input for consistent database storage.
    
    Our database schema requires lowercase, underscore-separated values
    for the username field to ensure case-insensitive lookups work correctly.
    """
    user_data = user_data.lower()
    user_data = user_data.strip()
    user_data = user_data.replace(' ', '_')
    return user_data

def greet(name: str) -> str:
    """Return a personalized greeting message.
    
    This function creates a friendly greeting that can be used
    in user interfaces to make the application feel more personal.
    
    Args:
        name: The name of the person to greet
        
    Returns:
        A formatted greeting string
        
    Raises:
        ValueError: If name is empty or contains only whitespace
    """
    if not name or not name.strip():
        raise ValueError("Name cannot be empty")
    return f"Hello, {name}! Welcome to our application."

# Get the docstring
print(greet.__doc__)

# Or use the help function
help(greet)

def fetch_user_data(user_id: int, include_private: bool = False) -> dict:
    """Fetch user data from the database.
    
    Retrieves user information from the primary database. For security reasons,
    private fields are only included when explicitly requested.
    
    Args:
        user_id: The unique identifier of the user
        include_private: Whether to include private user data (default: False)
        
    Returns:
        A dictionary containing user information with the following keys:
            - id: User ID
            - name: Full name
            - email: Email address
            - created_at: Account creation timestamp
            - private_data: Dict of private fields (only if include_private=True)
            
    Raises:
        UserNotFoundError: If the user_id doesn't exist
        DatabaseConnectionError: If database connection fails
        
    Example:
        >>> user = fetch_user_data(123, include_private=True)
        >>> print(user['name'])
        'John Doe'
    """
    pass

def calculate_statistics(data: list[float]) -> dict[str, float]:
    """
    Calculate basic statistical measures for a dataset.
    
    Parameters
    ----------
    data : list[float]
        Input data array. Must contain at least one element.
        
    Returns
    -------
    dict[str, float]
        Dictionary containing:
            - mean: Arithmetic mean of the data
            - median: Middle value when data is sorted
            - std: Standard deviation
            - min: Minimum value
            - max: Maximum value
            
    Raises
    ------
    ValueError
        If data is empty or contains non-numeric values
        
    See Also
    --------
    scipy.stats.describe : More comprehensive statistics
        
    Examples
    --------
    >>> data = [1, 2, 3, 4, 5]
    >>> stats = calculate_statistics(data)
    >>> print(stats['mean'])
    3.0
    """
    pass

def validate_email(email: str) -> bool:
    """Validate email address format.
    
    :param email: The email address to validate
    :type email: str
    :return: True if email is valid, False otherwise
    :rtype: bool
    :raises ValueError: If email parameter is not a string
    
    The validation checks for:
    
    * Basic email format (user@domain)
    * Valid characters in local and domain parts
    * Domain has at least one dot
    * No consecutive dots
    
    Example:
    
    .. code-block:: python
    
        >>> validate_email("user@example.com")
        True
        >>> validate_email("invalid-email")
        False
    """
    pass

def send_notification(message: str, recipients: list[str]) -> bool:
    """Send notification to multiple recipients.
    
    @param message: The notification message to send
    @type message: str
    @param recipients: List of recipient email addresses
    @type recipients: list[str]
    @return: True if all notifications were sent successfully
    @rtype: bool
    @raise ConnectionError: If the notification service is unavailable
    """
    pass

def process_payment(amount: float, currency: str, payment_method: str) -> dict:
    """
    
    @param amount:
    @param currency:
    @param payment_method:
    @return:
    """
    pass

{
    "autoDocstring.docstringFormat": "google",
    "autoDocstring.startOnNewLine": true,
    "autoDocstring.includeExtendedSummary": true
}

from typing import Optional, List, Dict, Any

def create_user(
    username: str,
    email: str,
    age: Optional[int] = None,
    preferences: Dict[str, Any] = None
) -> Dict[str, Any]:
    """Create a new user account.
    
    Args:
        username: Unique username for the account
        email: Valid email address
        age: User's age (optional)
        preferences: User preferences dictionary (optional)
        
    Returns:
        Dictionary containing the created user data
    """
    pass

def divide_numbers(a: float, b: float) -> float:
    """Divide two numbers.
    
    Args:
        a: Dividend
        b: Divisor
        
    Returns:
        Result of division
        
    Raises:
        ZeroDivisionError: If b is zero
        TypeError: If arguments are not numbers
    """
    if not isinstance(a, (int, float)) or not isinstance(b, (int, float)):
        raise TypeError("Arguments must be numbers")
    if b == 0:
        raise ZeroDivisionError("Cannot divide by zero")
    return a / b

import logging
from typing import Optional, Dict, Any
from html import H1, H2, H3, H4, H5, H6

log = logging.getLogger(__name__)

class ReportGenerator:
    """Generate HTML reports from structured data.
    
    This class provides functionality to create formatted HTML reports
    with headings, paragraphs, and tables. It's designed to work with
    data from various sources and can generate reports in different formats.
    
    Attributes:
        document: List containing HTML elements of the report
        title: The main title of the report
        author: The author of the report
    """
    
    def __init__(self, title: str, author: str = "Unknown"):
        """Initialize the report generator.
        
        Args:
            title: The main title for the report
            author: The author name (default: "Unknown")
        """
        self.document = []
        self.title = title
        self.author = author
        log.info(f"Initialized report '{title}' by {author}")
    
    def add_heading(self, text: str, level: int, **kwargs) -> None:
        """Adds heading to the report document.

        Heading is represented as HTML H1, H2, H3, H4, H5 or H6 tag.
        Heading text is defined by 'text' argument and level is defined by 'level'.
        When not supported level is provided the H1 tag is used.

        Args:
            text: Text of the heading
            level: Level of the heading. Integer from range 1 to 6
            **kwargs: Additional HTML attributes for the heading tag

        Raises:
            ValueError: If level is not between 1 and 6
        """
        if not 1 <= level <= 6:
            raise ValueError("Heading level must be between 1 and 6")
            
        # Try to find appropriate HTML tag, if not found use H1
        _header = getattr(html, f"H{level}", html.H1)
        log.debug(f"Heading{level}: '{text}' added.")
        self.document.append(_header(text))
        return None
    
    def generate_html(self) -> str:
        """Generate the complete HTML document.
        
        Returns:
            Complete HTML document as a string with proper DOCTYPE,
            head section, and body containing all added elements.
        """
        html_content = "\n".join(str(element) for element in self.document)
        return f"""
<!DOCTYPE html>
<html>
<head>
    <title>{self.title}</title>
    <meta charset="utf-8">
</head>
<body>
    {html_content}
    <footer>Generated by {self.author}</footer>
</body>
</html>
        """.strip()