Py Clean Functions

---
name: py-clean-functions
description: Use when writing, fixing, editing, or refactoring Python functions. Enforces Clean Code principles—maximum 3 arguments, single responsibility, no flag parameters. Also trigger on: functions with 4+ parameters, boolean flag parameters like `enabled=True`, functions that mutate their arguments in place, one-off `util`/`helper` functions that are never called, or asks like "too many arguments", "split this function", "is this still used". Also trigger on: helper functions defined above the entry point that calls them, a module that has to be read bottom-up, a function mixing orchestration with low-level detail, or asks like "does this read top-down", "stepdown rule", "should this read like a book", "what order should these functions go in".
---

# Clean Functions

## F1: Too Many Arguments (Maximum 3)

```python
# Bad - too many parameters
def create_user(name, email, age, country, timezone, language, newsletter):
    ...

# Good - use a dataclass or dict
@dataclass
class UserData:
    name: str
    email: str
    age: int
    country: str
    timezone: str
    language: str
    newsletter: bool

def create_user(data: UserData):
    ...
```

More than 3 arguments means your function is doing too much or needs 
a data structure.

## F2: No Output Arguments

Don't modify arguments as side effects. Return values instead.

```python
# Bad - modifies argument
def append_footer(report: Report) -> None:
    report.append("\n---\nGenerated by System")

# Good - returns new value
def with_footer(report: Report) -> Report:
    return report + "\n---\nGenerated by System"
```

## F3: No Flag Arguments

Boolean flags mean your function does at least two things.

```python
# Bad - function does two different things
def render(is_test: bool):
    if is_test:
        render_test_page()
    else:
        render_production_page()

# Good - split into two functions
def render_test_page(): ...
def render_production_page(): ...
```

## F4: Delete Dead Functions

If it's not called, delete it. No "just in case" code. Git preserves history.

## The Stepdown Rule: Code Reads Top-Down

A module should read like a narrative: the highest level of abstraction first, each function
followed by the ones it calls. The reader descends one level at a time and can stop as soon as
they know enough.

```python
# Bad - the reader meets encoding details before knowing what the module does
def _escape_quotes(value: str) -> str: ...
def _serialise_row(row: Row) -> str: ...
def export_orders(orders: list[Order]) -> str: ...   # the point, buried at the bottom

# Good - the story first, the details underneath
def export_orders(orders: list[Order]) -> str:
    return "\n".join(_serialise_row(o) for o in orders)

def _serialise_row(row: Row) -> str:
    return ",".join(_escape_quotes(field) for field in row)

def _escape_quotes(value: str) -> str:
    return value.replace('"', '""')
```

Two consequences follow:

**One level of abstraction per function.** A function mixing orchestration with string escaping has
no place in the ordering, because it belongs at two levels at once. That is the signal to split it.

```python
# Bad - policy and byte-level detail in one breath
def publish(post: Post) -> None:
    if post.author.is_banned: return
    body = post.body.replace("\r\n", "\n").strip()[:5000]
    db.execute("INSERT INTO posts ...", body)

# Good - each line is the same size of idea
def publish(post: Post) -> None:
    if _is_publishable(post):
        _store(post.author, _normalise(post.body))
```

**Vertical distance tracks relatedness.** Callee directly below caller. Variables declared close to
first use. Public functions before the private helpers they call. A reader should not scroll to
follow one thought.

If a file cannot be ordered this way, it holds more than one responsibility and wants splitting.