DEV Community: Sanjeev

How to Write Better Functions: A Clean Code Checklist

Sanjeev — Wed, 14 May 2025 02:59:43 +0000

Functions are the building blocks of your code - they break down complex operations into manageable, reusable pieces. Well-designed functions are key to creating systems that are easy to understand, test, and maintain over time.

This post presents four key checkpoints for reviewing functions, inspired by the book Clean Code. Each checkpoint includes practical examples showing common problems and their solutions.

Function Review Checklist

Is the function small, focused, and does its name match what it does?
Does the function have too many arguments?
Are errors handled with exceptions instead of error codes?
Is there any unnecessary duplication?

Checkpoint 1: Is the function small, focused, and does its name match what it does?

A function should do one thing and do it well. Here are three key signs of a focused function:

a. It works at one level of abstraction

Problem: High-level logic mixed with low-level logic

void processOrder(Order order) {
    if (!order.hasValidPayment()) {
        throw new InvalidOrderException("Payment validation failed");
    }
    // Low-level database operation mixed with high-level logic
    orderRepository.executeSQL("INSERT INTO orders VALUES (" + order.getId() + ", ...)");
}

Solution: Consistent abstraction level

void processOrder(Order order) {
    validateOrder(order);
    saveOrder(order);
}

b. It either does something (command) or answers something (query), but not both

Problem: Mixed command and query

int incrementAndGet() {
    count++;
    return count;
}

Solution: Separate command and query

void increment() {
    count++;
}

int getCount() {
    return count;
}

c. It doesn't have hidden side effects

Problem: Hidden side effect

double calculateTotal(Order order) {
    if (order.getTotal() > 100) {
        order.applyDiscount(10);  // Surprising! Calculating total but modifying order
    }
    return order.getTotal();
}

Solution: No side effects

double calculateTotal(Order order) {
    return order.getTotal();
}

void applyDiscountIfEligible(Order order) {
    if (calculateTotal(order) > 100) {
        order.applyDiscount(10);
    }
}

Checkpoint 2: Does the function have too many arguments?

Functions should have as few arguments as possible. Functions with too many arguments are hard to read, use, and test.
Here are common solutions to handle multiple parameters effectively:

a. Group related parameters into an object

Problem: Too many related arguments

void createUser(String name, String email, String phone, String address) {
    // User creation logic
}

Solution: Group related data into an object

void createUser(UserProfile profile) {
    // User creation logic
}

b. Use builder pattern for optional parameters

Problem: Multiple constructor variations

class Report {
    Report(String title) { ... }
    Report(String title, Date from) { ... }
    Report(String title, Date from, Date to) { ... }
}

Solution: Builder pattern for clear, flexible construction

Report report = new ReportBuilder()
    .setTitle("Sales Report")
    .setFromDate(startDate)    // Optional
    .setToDate(endDate)        // Optional
    .build();

Checkpoint 3: Are errors handled with exceptions instead of error codes?

Error codes mix error handling with normal flow and are easy to ignore. Exceptions make error cases explicit and separate them from the main logic. Example:

a. Use exceptions instead of error codes

Problem: Using error codes

int withdraw(Account account, double amount) {
    if (amount <= 0) return -1;        // Invalid amount
    if (amount > account.balance) return -2;  // Insufficient funds
    account.balance -= amount;
    return 0;  // Success
}

Solution: Using specific exceptions

void withdraw(Account account, double amount) {
    if (amount <= 0) {
        throw new InvalidAmountException("Amount must be positive");
    }
    if (amount > account.balance) {
        throw new InsufficientFundsException("Not enough balance");
    }
    account.balance -= amount;
}

Checkpoint 4: Is there any unnecessary duplication?

Duplicated code increases the risk of bugs and makes changes harder. Here's how to identify and eliminate common types of duplication:

a. Extract repeated validation logic

Problem: Duplicated validation

class UserService {
    void createUser(String email) {
        if (email == null || !email.contains("@")) {
            throw new InvalidEmailException();
        }
        // Create user
    }

    void updateEmail(String email) {
        if (email == null || !email.contains("@")) {
            throw new InvalidEmailException();
        }
        // Update email
    }
}

Solution: Single validation function

class UserService {
    private void validateEmail(String email) {
        if (email == null || !email.contains("@")) {
            throw new InvalidEmailException();
        }
    }

    void createUser(String email) {
        validateEmail(email);
        // Create user
    }

    void updateEmail(String email) {
        validateEmail(email);
        // Update email
    }
}

b. Create utility functions for common operations

Problem: Repeated string manipulation

String name1 = input1.trim().toLowerCase().replace(" ", "");
String name2 = input2.trim().toLowerCase().replace(" ", "");

Solution: Utility function

String standardizeName(String input) {
    return input.trim().toLowerCase().replace(" ", "");
}

Wrap-up

Well-designed functions make code easier to understand, test, and maintain. When reviewing code, check for:

Single responsibility with appropriate abstraction levels
Minimal, well-organized parameters
Clear error handling with exceptions
No unnecessary duplication

These improvements might seem small, but they compound to create significantly more maintainable systems.

Clean Code Naming: A Senior Developer’s Code Review Checklist

Sanjeev — Sat, 10 May 2025 19:54:28 +0000

Getting the names in your code right is crucial — it makes your code easier to read, maintain, and debug. But honestly, it’s not always obvious what makes a name good or bad, especially when you’re reviewing someone else’s code.

In this post, I’ll share my mental checklist for reviewing names during code reviews. It’s based on principles from Clean Code book, but expressed in a straightforward, practical way so you can start applying it today.

1. Does the name clearly tell you what it’s for?

The name should make the purpose of the variable, function, or class obvious. It should not require you to dig through the code or run around to figure it out. Be descriptive to provide enough context if it helps clarify the intent. Avoid vague or overly broad names.

Examples:

1.1 Vague name

// Problematic
List<String> data;  // what kind of data?

Better: Clear purpose

List<String> userEmails;  // clearer purpose

1.2 Names missing key info

void process(String input);  // process what? how?

Fix:

void validateEmailFormat(String email);  // clear purpose

2. Does the name match the actual meaning in the domain?

Use terms that make sense in the real world or in your tech stack. Mixing up terms can make the code confusing: developers might misinterpret what a variable or method actually does.

Examples:

2.1 Using a term incorrectly

class CacheKeyMapper {
    // 'mapper' sounds like converting objects
    String generateKey(String cacheValue); 
}

Correct: Use "generator" when you’re creating something

class CacheKeyGenerator {
    String generateKey(String cacheValue);
}

2.2 Use of vague term

class UserAccountDetails {
    // Sounds like this holds user info
    private String username;
    private String password;
    private String email;
}

Correct: actually, it only deals with login info.

class UserCredentials {
    private String username;
    private String password;
    private String email;
}

3. Is the name helping distinguish similar things?

If you have multiple similar methods or classes, give them clear, specific names so you know exactly what each one does. Also, stick to consistent patterns — it reduces mental overhead.

Examples:

3.1 No real difference

class OrderService {
    // Unclear distinctions
    Order getOrder(String id);
    Order fetchOrder(String id);
    Order retrieveOrder(String id);
}

Better: Specific roles

class OrderService {
    // Clear distinctions
    Order getOrderById(String id);
    Order getOrderByReference(String ref);
    List<Order> getOrdersByCustomer(String customerId);
}

3.2 Keep your method names uniform

class Account {
    float getBalance();
}

class CustomerInfo {
    String fetchShippingAddress();
}

Instead of mixing get and fetch, pick one:

class Account {
    float getBalance();
}

class CustomerInfo {
    String getShippingAddress();
}

Bonus tip: take inspiration from open-source projects

Open-source projects like Google Guava and Apache Commons provide excellent examples of effective naming. Aligning your naming conventions with theirs is always a good idea.

Wrap-up: Make it practical

Reviewing names isn’t about nitpicking. It’s about making your code understandable for others and for future you. Take a moment to ask:

Does this name tell me what it’s for?
Does it match the real-world or technical terms I understand?
Is it distinct enough from similar names?
Is it consistent with the rest of the code?

Good names save time and reduce bugs in both immediate development and long-term maintenance. Clean code starts with clear naming.