Clean Function Design in Rust

Welcome to your next step in mastering Clean Code! 🚀 In previous lessons, we discussed the importance of meaningful naming conventions. Now, we move into the realm of functions, which are the backbone of application logic and essential for code organization and execution. Structuring these functions effectively is vital for enhancing the clarity and maintainability of a codebase. In this lesson, we will explore best practices and techniques to ensure our code remains clean, efficient, and readable, leveraging Rust's powerful features.

Below are the key principles for writing clean functions in Rust:

• Keep functions small. Small functions are easier to read, comprehend, and maintain.
• Focus on a single task (Single Responsibility Principle). A function dedicated to one task is more reliable and easier to debug.
• Limit arguments to three or fewer. Excessive arguments make function signatures complicated and functions difficult to understand and use.
• Avoid boolean flags. Boolean flags can obscure the code's purpose; consider using enums to represent different behaviors more expressively.
• Eliminate side effects. Rust's default immutability helps prevent unintended side effects, making code more predictable and easier to understand; more generally, avoid altering external state or relying on external changes.
• Implement the DRY principle. Employ helper functions and leverage traits to reduce redundancy, enhance maintainability, and enable polymorphism.

Let's dive deeper into each of these principles.

Functions should remain small. If they become too large, consider splitting them into multiple, focused functions: while there's no strict limit on lines of code, maintaining readability and manageability is key.

Consider the process_order function below, which is manageable but has the potential to become unwieldy:

use log::{error, info};

// Not Clean - Overly Complex Function
fn process_order(order: &mut Order, inventory: &mut Inventory) {
    // Step 1: Validate the order
    if !order.is_valid() {
        error!("Invalid Order");
        return;
    }
    // Step 2: Process payment
    if !order.process_payment() {
        error!("Payment failed");
        return;
    }
    // Step 3: Update inventory
    inventory.update(order.get_items());

    // Step 4: Notify customer
    order.notify_customer();

    // Step 5: Log order processing
    info!("Order processed successfully");
}

To improve this process, we can extract each step into dedicated functions and handle errors idiomatically using the Result type and the ? operator:

use log::{error, info};

// Clean - Using Small Functions and Idiomatic Error Handling 🌟

fn process_order(order: &mut Order, inventory: &mut Inventory) -> Result<(), OrderError> {
    validate_order(order)?;
    process_payment(order)?;
    update_inventory(order, inventory)?;
    notify_customer(order)?;
    log_order_processing()?;
    Ok(())
}

fn validate_order(order: &Order) -> Result<(), OrderError> {
    if order.is_valid() {
        Ok(())
    } else {
        error!("Invalid Order");
        Err(OrderError::InvalidOrder)
    }
}

fn process_payment(order: &mut Order) -> Result<(), OrderError> {
    if order.process_payment() {
        Ok(())
    } else {
        error!("Payment failed");
        Err(OrderError::PaymentFailed)
    }
}

fn update_inventory(order: &Order, inventory: &mut Inventory) -> Result<(), InventoryError> {
    inventory.update(order.get_items())
}

fn notify_customer(order: &Order) -> Result<(), NotificationError> {
    order.notify_customer()
}

fn log_order_processing() -> Result<(), LogError> {
    info!("Order processed successfully");
    Ok(())
}

By breaking down process_order into smaller functions and using Result with the ? operator, we make error handling more idiomatic and the codebase cleaner. This approach also leverages Rust's powerful type system for better error management.

A function should embody the principle of doing one thing only, which is called the Single Responsibility Principle. If a function handles multiple responsibilities, it can become lengthy and harder to maintain, and you should consider reorganizing it. Let's see an example of a save_and_notify_user function that is both too long and does multiple different tasks at once:

// Not Clean - Function with Multiple Responsibilities
fn save_and_notify_user(
    user: &User,
    data_source: &DataSource,
    web_client: &WebClient,
) -> Result<(), Box<dyn Error>> {
    // Save the user to the database
    let sql = "INSERT INTO users (name, email) VALUES (?, ?)";
    let mut conn = data_source.get_connection()?;
    let mut stmt = conn.prepare(sql)?;
    stmt.execute(&[&user.name, &user.email])?;

    // Notify the user via web client
    web_client
        .post("/sendWelcomeEmail")
        .body(user)
        .send()?;

    Ok(())
}

In this snippet, the save_and_notify_user function is handling multiple responsibilities: interacting with the database to save the user and using a web client to send a notification email. This violates the Single Responsibility Principle and makes the function cumbersome.

To improve this code, we can create two dedicated functions for saving the user and sending the welcome email. This results in clear separation of concerns and dedicated responsibilities for each function:

// Clean - Single Responsibility with Proper Error Handling 🌟
fn save_and_notify_user(
    user: &User,
    data_source: &DataSource,
    web_client: &WebClient,
) -> Result<(), Box<dyn Error>> {
    save_user(user, data_source)?;
    notify_user(user, web_client)?;
    Ok(())
}

fn save_user(user: &User, data_source: &DataSource) -> Result<(), SaveError> {
    let sql = "INSERT INTO users (name, email) VALUES (?, ?)";
    let mut conn = data_source.get_connection()?;
    let mut stmt = conn.prepare(sql)?;
    stmt.execute(&[&user.name, &user.email])?;
    Ok(())
}

fn notify_user(user: &User, web_client: &WebClient) -> Result<(), NotificationError> {
    web_client
        .post("/sendWelcomeEmail")
        .body(user)
        .send()
        .map_err(NotificationError::SendFailed)
}

By refactoring the code, each function now has a single responsibility: save_user handles database operations, and notify_user manages sending the email. This adheres to the Single Responsibility Principle, enhances code readability, and makes maintenance easier.

Keeping the number of function arguments to a minimum enhances readability and usability. Aim for no more than three parameters.

Consider the save_address function with five arguments, which makes the function less readable:

// Not Clean - Too Many Arguments
fn save_address(street: &str, city: &str, state: &str, zip_code: &str, country: &str) {
    // Logic to save address
}

A cleaner approach encapsulates the details into an Address struct, reducing the number of arguments:

// Clean - Using a Struct to Encapsulate Data 🌟
struct Address {
    street: String,
    city: String,
    state: String,
    zip_code: String,
    country: String,
}

fn save_address(address: &Address) {
    // Logic to save address
}

Using boolean flags in functions often suggests that the function may be handling multiple responsibilities or behaviors, leading to increased complexity and reduced clarity. Instead, it's better to use enums to represent different states or actions explicitly.

Consider the set_privileges function below, which uses a boolean flag to determine whether to grant or revoke admin rights:

// Not Clean - Using a Boolean Flag
fn set_privileges(user: &mut User, admin: bool) {
    if admin {
        // Logic for granting admin rights
    } else {
        // Logic for removing admin rights
    }
}

In this example, the admin flag controls two different behaviors within the same function. This can make the code harder to understand and maintain, as the meaning of true or false isn't immediately clear without additional context. A cleaner approach is to use an enum to represent the privilege action explicitly, enhancinh clarity and expressiveness:

// Clean - Using an Enum for Clarity 🌟
enum PrivilegeAction {
    GrantAdmin,
    RevokeAdmin,
}

fn set_privileges(user: &mut User, action: PrivilegeAction) {
    match action {
        PrivilegeAction::GrantAdmin => {
            // Logic for granting admin rights
        }
        PrivilegeAction::RevokeAdmin => {
            // Logic for removing admin rights
        }
    }
}

By using enums and pattern matching, we make the possible actions explicit: the function set_privileges now takes action: PrivilegeAction as a parameter, and the match expression handles each case clearly. This approach eliminates the ambiguity associated with boolean flags, making the code more readable and less error-prone.

Avoid side effects by not modifying external state. Rust’s default immutability and borrowing rules help achieve this, making code more predictable and easier to debug.

Below, the add_to_total function demonstrates a side effect by modifying external state:

// Not Clean - Side Effect
static mut TOTAL: i32 = 0;

fn add_to_total(value: i32) -> i32 {
    unsafe {
        TOTAL += value;
        TOTAL
    }
}

A cleaner calculate_total function avoids side effects by not altering external state:

// Clean - No Side Effect 🌟
fn calculate_total(initial: i32, value: i32) -> i32 {
    initial + value
}

By returning new values instead of modifying external variables, we maintain function purity and make our code safer. Rust's default to immutability means variables are immutable unless explicitly declared with mut, helping prevent unintended modifications.

Reduce code redundancy by introducing helper functions and leveraging traits where applicable.

Below, both print_user_info and print_manager_info repeat similar logic, violating the DRY principle:

// Not Clean - Repetitive Code
fn print_user_info(user: &User) {
    println!("Name: {}", user.name);
    println!("Email: {}", user.email);
}

fn print_manager_info(manager: &Manager) {
    println!("Name: {}", manager.name);
    println!("Email: {}", manager.email);
}

To adhere to the DRY principle, we use a Person trait and implement it for both User and Manager:

// Clean - Using a Trait for Polymorphism 🌟
trait Person {
    fn name(&self) -> &str;
    fn email(&self) -> &str;
}

impl Person for User {
    fn name(&self) -> &str {
        &self.name
    }

    fn email(&self) -> &str {
        &self.email
    }
}

impl Person for Manager {
    fn name(&self) -> &str {
        &self.name
    }

    fn email(&self) -> &str {
        &self.email
    }
}

fn print_info<T: Person>(person: &T) {
    println!("Name: {}", person.name());
    println!("Email: {}", person.email());
}

By using a trait, we enable polymorphism and code abstraction, allowing us to write generalized functions that can operate on any type implementing the Person trait. This aligns with Rust's design philosophy and promotes code reusability.

In this lesson, we explored the importance of clean functions in maintaining readable and maintainable code. By keeping functions small, adhering to the Single Responsibility Principle, limiting arguments, avoiding boolean flags, eliminating side effects, and embracing the DRY principle—while leveraging Rust's features like error handling with Result, default immutability, traits for polymorphism, and standard logging practices—you set a strong foundation for clean coding in Rust. Next, we'll practice these principles to enhance your coding skills further! 🎓