clean-functions

name	clean-functions
description	Use when refactoring or reviewing Python functions for size, arguments, side effects, or single-responsibility problems. Focus on focused cleanup, not broad architectural rewrites.

Clean Functions

In This Repo

• Use this skill when a Python function needs to be split, simplified, or made easier to read.
• Keep changes local and proportional unless the task explicitly asks for a larger refactor.
• If a function change materially affects contract behavior, keep write-contract as the source of truth.

F1: Too Many Arguments

Aim for three arguments or fewer. More than that usually means the function is doing too much or wants a data structure.

# Bad
def create_user(name, email, age, country, timezone, language, newsletter):
    ...

# Good
@dataclass
class UserData:
    name: str
    email: str
    age: int
    country: str
    timezone: str
    language: str
    newsletter: bool

def create_user(data: UserData):
    ...

F2: No Output Arguments

Do not modify arguments as a hidden side effect when a return value is clearer.

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

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

F3: No Flag Arguments

Boolean flags often mean the function is doing at least two things.

# Bad
def render(is_test: bool):
    if is_test:
        render_test_page()
    else:
        render_production_page()

# Good
def render_test_page():
    ...

def render_production_page():
    ...

F4: Delete Dead Functions

If a function is not used and no longer belongs to the design, delete it. Do not keep "just in case" helpers in the file.