✨ Best Practices — Writing Clean, Efficient Functions

Write functions that are maintainable, efficient, and a joy to work with.

📝 Naming Conventions

Function Names Should Be Descriptive

# ❌ Bad — unclear what it does
def process(x):
    return x * 2

# ✅ Good — clear purpose
def double_number(x):
    return x * 2

# ✅ Better — even more descriptive
def calculate_doubled_value(value):
    return value * 2

Use Verbs for Actions

# ✅ Good — verbs indicate what function does
def get_user_name(user_id):
    pass

def validate_email(email):
    pass

def send_notification(message):
    pass

# ❌ Bad — unclear action
def user_name(user_id):
    pass

def email(email):
    pass

📚 Documentation and Docstrings

Include Docstrings

def calculate_bmi(weight_kg, height_m):
    """
    Calculate Body Mass Index.

    Args:
        weight_kg (float): Weight in kilograms
        height_m (float): Height in meters

    Returns:
        float: BMI value

    Example:
        >>> calculate_bmi(70, 1.75)
        22.86
    """
    return weight_kg / (height_m ** 2)

Document Edge Cases

def divide_safe(a, b):
    """
    Divide two numbers safely.

    Args:
        a (float): Numerator
        b (float): Denominator

    Returns:
        float: Result of a / b, or None if division by zero

    Note:
        Returns None rather than raising exception to handle
        division by zero gracefully.
    """
    if b == 0:
        return None
    return a / b

✅ Single Responsibility Principle

Each function should do ONE thing:

# ❌ Bad — does too much
def process_user_data(user_id):
    user = fetch_user_from_db(user_id)
    user["age"] = 2024 - user["birth_year"]
    send_email_notification(user["email"])
    save_to_cache(user)
    log_activity(user_id)
    return user

# ✅ Good — each function has one job
def get_user_with_age(user_id):
    user = fetch_user_from_db(user_id)
    user["age"] = 2024 - user["birth_year"]
    return user

def notify_user(user):
    send_email_notification(user["email"])

def cache_user(user):
    save_to_cache(user)

def log_access(user_id):
    log_activity(user_id)

# In main code
user = get_user_with_age(user_id)
notify_user(user)
cache_user(user)
log_access(user_id)

🔒 Keep Functions Small

Shorter functions are easier to test and debug:

# ❌ Bad — 30 lines doing multiple things
def process_order(order_id):
    # Fetch order
    # Validate items
    # Calculate totals
    # Apply discounts
    # Check inventory
    # Process payment
    # Send confirmation
    # Update database
    # ... (24 more lines)

# ✅ Good — small, focused functions
def validate_order(order):
    return all(item["quantity"] > 0 for item in order["items"])

def calculate_order_total(order):
    return sum(item["price"] * item["quantity"] for item in order["items"])

def apply_discount(total, discount_percent):
    return total * (1 - discount_percent / 100)

def process_order(order_id):
    order = fetch_order(order_id)
    if not validate_order(order):
        raise ValueError("Invalid order")
    total = calculate_order_total(order)
    total = apply_discount(total, order.get("discount", 0))
    process_payment(total)
    return order

📤 Return Values Consistency

Always return the same type:

# ❌ Bad — inconsistent return types
def find_user(name):
    if name:
        return {"name": name}  # dict
    else:
        return "Not found"  # string

# ✅ Good — always returns dict or None
def find_user(name):
    if name:
        return {"name": name}
    return None

# ✅ Better — explicit error handling
def find_user(name):
    if not name:
        raise ValueError("Name cannot be empty")
    return {"name": name}

⚡ Performance Optimization

Cache Expensive Computations

from functools import lru_cache

# ❌ Bad — recalculates every time
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

fibonacci(35)  # Takes 3+ seconds!

# ✅ Good — caches results
@lru_cache(maxsize=128)
def fibonacci_cached(n):
    if n <= 1:
        return n
    return fibonacci_cached(n - 1) + fibonacci_cached(n - 2)

fibonacci_cached(35)  # Instant!

Avoid Redundant Operations

# ❌ Bad — calculates length multiple times
def process_list(items):
    result = []
    for i in range(len(items)):  # Length calculated each iteration
        if items[i] > 0:  # Accessing item again
            result.append(items[i] * 2)  # Accessing again
    return result

# ✅ Good — cleaner and more efficient
def process_list(items):
    return [item * 2 for item in items if item > 0]

🛡️ Input Validation

Validate at function boundaries:

# ❌ Bad — no validation
def divide(a, b):
    return a / b

# ✅ Good — validates inputs
def divide(a, b):
    if not isinstance(a, (int, float)):
        raise TypeError("a must be numeric")
    if not isinstance(b, (int, float)):
        raise TypeError("b must be numeric")
    if b == 0:
        raise ValueError("Division by zero not allowed")
    return a / b

🎯 Default Arguments vs Optional

Use sensible defaults:

# ❌ Bad — forces users to specify everything
def create_config(model, temperature, max_tokens, top_p, frequency_penalty):
    pass

# ✅ Good — reasonable defaults
def create_config(
    model="GPT-4",
    temperature=0.7,
    max_tokens=1000,
    top_p=1.0,
    frequency_penalty=0.0
):
    pass

# Usage
config1 = create_config()  # All defaults
config2 = create_config(temperature=0.3)  # Override one

🔄 Avoid Side Effects

Functions shouldn't modify external state:

# ❌ Bad — modifies global state
global_list = []

def add_item(item):
    global_list.append(item)  # Side effect!
    return len(global_list)

# ✅ Good — pure function
def add_item(item, items=None):
    if items is None:
        items = []
    items = items + [item]  # Creates new list
    return items, len(items)

❌ Common Anti-Patterns

Anti-Pattern 1: Flag Parameters

# ❌ Bad — flag parameter makes function do two things
def process_data(data, save_to_file=False):
    result = transform(data)
    if save_to_file:
        write_file("output.txt", result)
    return result

# ✅ Good — separate concerns
def process_data(data):
    return transform(data)

def process_and_save(data, filename):
    result = process_data(data)
    write_file(filename, result)
    return result

Anti-Pattern 2: Long Parameter Lists

# ❌ Bad — too many parameters
def create_user(name, email, age, city, country, phone, address, zip_code):
    pass

# ✅ Good — group related data
def create_user(name, email, details):
    # details = {age, city, country, phone, address, zip_code}
    pass

# Even better — use dataclass
from dataclasses import dataclass

@dataclass
class UserDetails:
    age: int
    city: str
    country: str
    phone: str
    address: str
    zip_code: str

def create_user(name: str, email: str, details: UserDetails):
    pass

Anti-Pattern 3: Modifying Parameters

# ❌ Bad — modifies input list
def add_prefix(prefix, items):
    for i in range(len(items)):
        items[i] = prefix + items[i]  # Modifies!
    return items

# ✅ Good — returns new list
def add_prefix(prefix, items):
    return [prefix + item for item in items]

🧪 Testability

Write functions that are easy to test:

# ❌ Bad — hard to test (depends on external systems)
def process_order(order_id):
    order = fetch_from_database(order_id)  # External dependency
    total = calculate_total(order)
    send_to_payment_api(total)  # External dependency
    return True

# ✅ Good — pure logic, testable
def calculate_order_total(order):
    """Pure function — no side effects."""
    return sum(item["price"] * item["qty"] for item in order["items"])

# Dependency injection — pass dependencies in
def process_order(order_id, db_fetch, payment_api):
    order = db_fetch(order_id)
    total = calculate_order_total(order)
    payment_api.charge(total)
    return True

# Tests
def test_calculate_total():
    order = {"items": [{"price": 10, "qty": 2}]}
    assert calculate_order_total(order) == 20

📋 Error Handling

Choose appropriate error strategies:

# Strategy 1: Raise exceptions
def get_positive_number(n):
    if n <= 0:
        raise ValueError("Must be positive")
    return n

# Strategy 2: Return None
def safe_divide(a, b):
    if b == 0:
        return None
    return a / b

# Strategy 3: Return default
def get_config(key, default=None):
    config = load_config()
    return config.get(key, default)

# Choose based on context:
# - Raise: Program error, must be fixed
# - Return None: Optional operation, caller can handle
# - Default: Configuration, sensible fallback

🔑 Quick Reference Checklist

✅ Clear, descriptive name
✅ Docstring with Args/Returns
✅ Single responsibility
✅ Small and focused
✅ Consistent return types
✅ Input validation
✅ Sensible defaults
✅ No side effects
✅ Easy to test
✅ Efficient algorithm
✅ Handles edge cases
✅ Good error messages

📊 Summary Table

🎯 When You See Code

Ask yourself:

• What does this function do?

• Could I test it easily?

• Does it have a side effect?

• Is the name clear?

• Is it doing one thing?

• Can I refactor it?

🎓 Advanced Topics

Ready to level up? Explore:

• **Design Patterns** — Decorator, Strategy, Factory

• **Type Hints** — Full typing for better code

• **Async Functions** — Concurrent execution

• **Testing Strategies** — Unit tests, mocks, fixtures

📚 What You've Completed

The Functions topic now covers:

✅ Why functions matter

✅ Parameters and arguments

✅ Return statements

✅ Local vs global scope

✅ Advanced features (*args, **kwargs, defaults)

✅ Lambda functions

✅ Decorators

✅ Functional programming (map, filter, reduce)

✅ Best practices and patterns

You're now a functions expert!

Ready to put it all together? Try comprehensive challenges or take the full quiz