Функции: Лучшие практики

# Плохо
def f(x, y): ...
def process(): ...

# Хорошо
def calculate_total_price(base_price, quantity, tax_rate): ...
def validate_email(email): ...

def is_adult(age): return age >= 18
def has_permission(user): return user.role == "admin"
def can_withdraw(balance, amount): return balance >= amount

# Плохо: одна функция делает всё
def process_user(name, age):
    if age < 18: return False
    with open("users.txt", "a") as f: f.write(f"{name},{age}\n")
    send_email(name)
    save_to_db(name, age)
    return True

# Хорошо: каждая функция — одно дело
def is_adult(age): return age >= 18
def save_user_to_file(name, age): ...
def send_welcome_email(name): ...

def register_user(name, age):
    """Зарегистрировать нового пользователя."""
    if not is_adult(age): return False
    save_user_to_file(name, age)
    send_welcome_email(name)
    return True

# Плохо: смешаны вычисление и вывод
def calculate_discount(price, pct):
    result = price * (1 - pct / 100)
    print(f"Итого: {result}")
    return result

# Хорошо: логика отделена от отображения
def calculate_discount(price, discount_percent):
    """Вычислить цену со скидкой."""
    return price * (1 - discount_percent / 100)

def show_discount_info(price, discount_percent):
    final = calculate_discount(price, discount_percent)
    print(f"Цена: {price} руб. → {final} руб.")

# Плохо
def f(x, y, z): return x + y * z

# Хорошо — именованные аргументы при вызове
def calculate_total_price(base_price, quantity, tax_rate):
    """Вычислить общую стоимость с налогом."""
    return base_price + quantity * tax_rate

result = calculate_total_price(base_price=10, quantity=5, tax_rate=2)

# Плохо: меняет переданный список
def add_item(items, new_item):
    items.append(new_item)  # побочный эффект!

# Хорошо: возвращает новый список
def add_item(items, new_item):
    """Вернуть новый список с добавленным элементом."""
    return items + [new_item]

def create_account(name, balance=0, currency="RUB"):
    """Создать банковский счёт."""
    return {"name": name, "balance": balance, "currency": currency}

account1 = create_account("Алиса")
account2 = create_account("Боб", 1000)
account3 = create_account("Чарли", 500, "USD")

# Плохо
def calc(p, d): return p - (p * d / 100)

# Хорошо
def calculate_discounted_price(price, discount_percent):
    """
    Вычислить цену со скидкой.

    Args:
        price: Начальная цена товара
        discount_percent: Процент скидки (0-100)

    Returns:
        Цена после применения скидки

    Example:
        >>> calculate_discounted_price(1000, 20)
        800.0
    """
    return price * (1 - discount_percent / 100)

def process_order(order_id):
    """Обработать заказ полностью."""
    order = validate_order(order_id)
    if not check_inventory(order): return False
    save_order_to_database(order)
    send_confirmation_email(order)
    return True