# CORRECT - one-liner for private helper
def _normalize_vector(vec: list[float]) -> list[float]:
    """Normalize vector to unit length."""
    magnitude = sum(x**2 for x in vec) ** 0.5
    return [x / magnitude for x in vec]

# CORRECT - comprehensive if complex private function
def _parse_nested_config(raw: dict[str, Any]) -> Config:
    """Parse nested configuration with inheritance resolution.

    Args:
        raw (dict[str, Any]): Raw config dictionary with potential $ref keys.

    Returns:
        Config: Resolved configuration object.
    """
    ...

# INCORRECT - no docstring on private function
def _normalize_vector(vec: list[float]) -> list[float]:
    magnitude = sum(x**2 for x in vec) ** 0.5
    return [x / magnitude for x in vec]

def function_name(param1: Type1, param2: Type2) -> ReturnType:
    """One-line summary of what the function does.

    Extended description explaining WHY this function exists and WHEN to use it.
    Do not explain HOW it works (the code shows that).

    Args:
        param1 (Type1): Description of first parameter.
        param2 (Type2): Description of second parameter.

    Returns:
        ReturnType: Description of return value.

    Raises:
        ExceptionType: When this exception is raised.

    Examples:
        >>> function_name(value1, value2)
        expected_output
    """

def calculate_similarity(embedding_a: list[float], embedding_b: list[float]) -> float:
    """Calculate cosine similarity between two embeddings.

    Use this for comparing semantic similarity of text chunks when building
    retrieval systems. Values closer to 1.0 indicate higher similarity.

    Args:
        embedding_a (list[float]): First embedding vector.
        embedding_b (list[float]): Second embedding vector.

    Returns:
        float: Cosine similarity score between -1.0 and 1.0.

    Raises:
        ValueError: If vectors have different dimensions.

    Examples:
        >>> calculate_similarity([1.0, 0.0], [1.0, 0.0])
        1.0
    """

class ClassName:
    """One-line summary of what the class represents.

    Extended description of the class purpose and when to use it.

    Attributes:
        attr1 (Type1): Description of public attribute.
        attr2 (Type2): Description of public attribute.

    Examples:
        >>> obj = ClassName(param)
        >>> obj.method()
        expected_output
    """

    def __init__(self, param: Type) -> None:
        """Initialize the class.

        Args:
            param (Type): Description of parameter.
        """

"""One-line summary of module purpose.

Extended description of what the module provides and when to use it.
"""

import ...

"""Embedding utilities for vector similarity search.

This module provides functions for creating, comparing, and manipulating
embeddings used in semantic search and retrieval systems.
"""

from typing import Final
...

# CORRECT - explains why this approach was chosen
# Use binary search here because the list is sorted and can have 100k+ items
index = bisect.bisect_left(sorted_items, target)

# CORRECT - explains a non-obvious constraint
# Must check expiry before validation because expired tokens fail silently
if token.is_expired():
    raise TokenExpiredError()

# INCORRECT - explains what (the code already shows this)
# Get the index using binary search
index = bisect.bisect_left(sorted_items, target)

# INCORRECT - obvious from the code
# Increment the counter
counter += 1

# INCORRECT - no docstring on public function
def fetch_user(user_id: int) -> User:
    return db.query(User).get(user_id)

# INCORRECT - no docstring on private function
def _hash_password(password: str) -> str:
    return hashlib.sha256(password.encode()).hexdigest()

# INCORRECT - docstring explains "how" instead of "why"
def fetch_user(user_id: int) -> User:
    """Query the database for a user by ID and return the User object."""
    return db.query(User).get(user_id)

# INCORRECT - missing Args/Returns sections
def fetch_user(user_id: int) -> User:
    """Fetch a user from the database."""
    return db.query(User).get(user_id)

def add_vectors(a: list[float], b: list[float]) -> list[float]:
    """Add two vectors element-wise.

    Args:
        a (list[float]): First vector.
        b (list[float]): Second vector.

    Returns:
        list[float]: Element-wise sum.

    Examples:
        >>> add_vectors([1.0, 2.0], [3.0, 4.0])
        [4.0, 6.0]
        >>> add_vectors([0.0], [0.0])
        [0.0]
    """