PEP 257: Docstring Conventions for Self-Documenting Code

def get_user_by_id(user_id):
    """Return user object for the given ID."""
    return database.users.find_one({"_id": user_id})

# Access the docstring at runtime
print(get_user_by_id.__doc__)
# Output: Return user object for the given ID.

# Good - prescriptive command ending with period
def clear_cache():
    """Clear all cached data from memory."""
    cache.clear()

# Bad - descriptive instead of prescriptive
def clear_cache():
    """This function clears the cache."""
    cache.clear()

# Bad - restates the obvious signature
def square(x):
    """square(x) -> x squared"""  # Don't repeat signature
    return x * x

# Good - describes what it returns
def square(x):
    """Return the square of x."""
    return x * x

def calculate_compound_interest(principal, rate, years, compound_freq=1):
    """Calculate compound interest with flexible compounding frequency.

    This function computes the final amount after applying compound
    interest over a specified period with customizable compounding frequency.

    Args:
        principal (float): Initial investment amount in dollars
        rate (float): Annual interest rate as decimal (0.05 for 5%)
        years (int): Number of years to compound
        compound_freq (int): Times per year to compound (default: 1)

    Returns:
        float: Final amount after compound interest

    Raises:
        ValueError: If principal or rate is negative
    """
    if principal < 0 or rate < 0:
        raise ValueError("Principal and rate must be non-negative")

    return principal * (1 + rate / compound_freq) ** (years * compound_freq)

class UserAccountManager:
    """Manage user account operations and authentication.

    This class provides methods for creating, validating, and managing
    user accounts including password verification and session handling.

    Public Methods:
        create_account: Register a new user account
        authenticate: Verify user credentials
        reset_password: Initiate password reset process

    Attributes:
        max_attempts (int): Maximum login attempts before lockout
    """

    def __init__(self, max_attempts=3):
        """Initialize the account manager.

        Args:
            max_attempts (int): Maximum login attempts allowed (default: 3)
        """
        self.max_attempts = max_attempts

    def authenticate(self, username, password):
        """Verify user credentials and create session.

        Args:
            username (str): User's login name
            password (str): User's password (will be hashed)

        Returns:
            Session: Active session object if successful

        Raises:
            AuthenticationError: If credentials are invalid
        """
        # Implementation here
        pass

"""User authentication and authorization utilities.

This module provides functions and classes for managing user authentication,
including password hashing, session management, and permission checking.

Exported Classes:
    UserAccountManager: Main authentication handler
    Session: User session representation

Exported Functions:
    hash_password: Securely hash passwords with salt
    verify_password: Compare password against stored hash

Example:
    >>> from auth import UserAccountManager
    >>> manager = UserAccountManager()
    >>> session = manager.authenticate('alice', 'secret123')
"""

import hashlib
from datetime import datetime

class BaseHandler:
    def process(self, data):
        """Process incoming data and return result."""
        return self.transform(data)

class CustomHandler(BaseHandler):
    def process(self, data):
        """Override process to add validation step."""
        if not self.validate(data):
            raise ValueError("Invalid data")
        return super().process(data)

class LoggingHandler(BaseHandler):
    def process(self, data):
        """Extend process to log all operations."""
        result = super().process(data)
        self.log_operation(data, result)
        return result

# Good - closing quotes on separate line for multi-line
def complex_operation():
    """Perform complex multi-step operation.

    This function coordinates several subsystems to achieve
    the desired outcome with proper error handling.
    """
    pass

# Good - stay on one line if it fits
def simple_operation():
    """Return True if operation succeeds."""
    return True

# Bad - don't use uppercase for parameter names in prose
def bad_docs(user_id):
    """Find user with USER_ID."""  # Don't do this
    pass

# Good - use lowercase in prose
def good_docs(user_id):
    """Find user with the given user_id."""
    pass