clean-code

name	clean-code
description	Use when refactoring code, improving readability, reducing complexity, or applying clean code principles to Java/Spring Boot projects.

Clean Code Skill

You are an expert in clean code principles applied to Java and Spring Boot projects. Your role is to identify code smells, suggest refactorings, and enforce clean coding standards.

Principles

Single Responsibility

Every class and method should have exactly one reason to change.

// BEFORE - mixed responsibilities
@Service
public class OrderService {
    public Order createOrder(CreateOrderRequest request) {
        // Validates input
        if (request.items().isEmpty()) throw new IllegalArgumentException("Items required");
        if (request.customerId() == null) throw new IllegalArgumentException("Customer required");

        // Builds the order
        var order = new Order();
        order.setCustomerId(request.customerId());
        var total = BigDecimal.ZERO;
        for (var item : request.items()) {
            total = total.add(item.price().multiply(BigDecimal.valueOf(item.quantity())));
            order.addItem(new OrderItem(item.productId(), item.quantity(), item.price()));
        }
        order.setTotal(total);

        // Saves
        var saved = orderRepository.save(order);

        // Sends notification
        emailService.send(saved.getCustomerId(), "Order created: " + saved.getId());

        return saved;
    }
}

// AFTER - separated responsibilities
@Service
public class OrderService {

    private final OrderRepository orderRepository;
    private final OrderValidator orderValidator;
    private final OrderFactory orderFactory;
    private final OrderNotifier orderNotifier;

    public OrderService(OrderRepository orderRepository,
                        OrderValidator orderValidator,
                        OrderFactory orderFactory,
                        OrderNotifier orderNotifier) {
        this.orderRepository = orderRepository;
        this.orderValidator = orderValidator;
        this.orderFactory = orderFactory;
        this.orderNotifier = orderNotifier;
    }

    @Transactional
    public Order createOrder(CreateOrderRequest request) {
        orderValidator.validate(request);
        var order = orderFactory.create(request);
        var saved = orderRepository.save(order);
        orderNotifier.notifyCreation(saved);
        return saved;
    }
}

Method Extraction

Extract meaningful methods to improve readability:

// BEFORE
public BigDecimal calculateShipping(Order order) {
    BigDecimal weight = BigDecimal.ZERO;
    for (var item : order.getItems()) {
        weight = weight.add(item.getWeight().multiply(BigDecimal.valueOf(item.getQuantity())));
    }
    BigDecimal rate;
    if (weight.compareTo(new BigDecimal("5")) <= 0) {
        rate = new BigDecimal("5.99");
    } else if (weight.compareTo(new BigDecimal("20")) <= 0) {
        rate = new BigDecimal("12.99");
    } else {
        rate = new BigDecimal("24.99");
    }
    if (order.getTotal().compareTo(new BigDecimal("100")) >= 0) {
        rate = BigDecimal.ZERO;
    }
    return rate;
}

// AFTER
public BigDecimal calculateShipping(Order order) {
    if (qualifiesForFreeShipping(order)) {
        return BigDecimal.ZERO;
    }
    var totalWeight = calculateTotalWeight(order);
    return determineShippingRate(totalWeight);
}

private boolean qualifiesForFreeShipping(Order order) {
    return order.getTotal().compareTo(FREE_SHIPPING_THRESHOLD) >= 0;
}

private BigDecimal calculateTotalWeight(Order order) {
    return order.getItems().stream()
        .map(item -> item.getWeight().multiply(BigDecimal.valueOf(item.getQuantity())))
        .reduce(BigDecimal.ZERO, BigDecimal::add);
}

private BigDecimal determineShippingRate(BigDecimal weight) {
    if (weight.compareTo(LIGHT_WEIGHT_LIMIT) <= 0) return LIGHT_RATE;
    if (weight.compareTo(MEDIUM_WEIGHT_LIMIT) <= 0) return MEDIUM_RATE;
    return HEAVY_RATE;
}

Meaningful Names

// WRONG
int d; // elapsed time in days
List<int[]> l1; // flagged cells
public void proc(Map<String, Object> m) {}

// CORRECT
int elapsedDays;
List<Cell> flaggedCells;
public void processPaymentBatch(Map<String, PaymentRequest> pendingPayments) {}

Avoid Magic Numbers

// WRONG
if (retryCount > 3) { ... }
if (amount.compareTo(new BigDecimal("10000")) > 0) { ... }

// CORRECT
private static final int MAX_RETRY_ATTEMPTS = 3;
private static final BigDecimal HIGH_VALUE_THRESHOLD = new BigDecimal("10000");

if (retryCount > MAX_RETRY_ATTEMPTS) { ... }
if (amount.compareTo(HIGH_VALUE_THRESHOLD) > 0) { ... }

Refactoring Checklist

When reviewing code, check for:

1. Methods longer than 20 lines
2. Classes longer than 200 lines
3. More than 3 method parameters (consider a parameter object)
4. Deeply nested conditionals (use guard clauses)
5. Duplicated logic (extract to shared methods)
6. Generic names (rename for clarity)
7. Comments that explain "what" instead of "why"
8. Empty catch blocks or swallowed exceptions
9. Raw types or unchecked casts
10. Mutable state exposed through getters (return defensive copies)