---
applyTo: "**"
---

# Project General Coding Standards (Python - PEP 8)

## Naming Conventions

- Follow PEP 8 naming conventions strictly
- Use `snake_case` for variables, functions, and methods
- Use `PascalCase` for class names
- Use `UPPER_CASE` for constants
- Prefix internal/private attributes with a single underscore (`_`)
- Avoid single-letter variable names unless in very small scopes (e.g., loops)

---

## Code Style & Formatting

- Follow PEP 8 guidelines for formatting
- Use 4 spaces for indentation (never tabs)
- Limit lines to 79 characters when possible (max 88 if using Black)
- Add a blank line between logical sections of code
- Keep imports organized:
  1. Standard library
  2. Third-party packages
  3. Local imports
- Avoid wildcard imports (`from module import *`)
- Remove unused imports and variables

---

## Clean Code Principles

- Write small, focused functions that do **one thing only**
- Prefer functions over long procedural blocks
- Keep functions under ~30 lines when possible
- Use descriptive and meaningful names
- Avoid code duplication (DRY principle)
- Prefer explicit code over implicit behavior
- Avoid deeply nested logic (max 2–3 levels)
- Use early returns to reduce nesting
- Keep classes focused and cohesive
- Write code that is easy to read and maintain

---

## Function Design

- Always use functions when logic can be reused or isolated
- Add type hints to all function signatures
- Keep functions pure when possible (avoid side effects)
- Document functions using docstrings (PEP 257 style)

Example:

```python
def calculate_average(values: list[float]) -> float:
    """
    Calculate the average of a list of numbers.

    Args:
        values: A list of float numbers.

    Returns:
        The arithmetic mean of the values.
    """
    if not values:
        raise ValueError("The values list cannot be empty.")

    return sum(values) / len(values)