Clean Code Principles

What is Clean Code?

Clean code is code that's easy to understand, easy to change, and easy to test — it communicates its intent directly, rather than requiring a reader to mentally execute it line by line to figure out what it's for.

Meaningful Names

Use Intention-Revealing Names

// BAD — what does this even do?
int d;
List<int[]> list1;

public List<int[]> getThem() {
    List<int[]> list1 = new ArrayList<>();
    for (int[] x : theList) {
        if (x[0] == 4)
            list1.add(x);
    }
    return list1;
}

// GOOD — clear intent, no need to guess what "4" or "x[0]" mean
int daysSinceLastOrder;
List<Order> overdueOrders;

public List<Order> getOverdueOrders() {
    List<Order> overdueOrders = new ArrayList<>();
    for (Order order : allOrders) {
        if (order.getStatus() == OrderStatus.OVERDUE) {
            overdueOrders.add(order);
        }
    }
    return overdueOrders;
}

Avoid Encodings

// BAD — Hungarian notation and prefixes the type system already tells you
String strName;
ICustomerService m_customerService;
int iCount;

// GOOD — let the type system do its job
String name;
CustomerService customerService;
int count;

Class Names vs Method Names

// Classes: nouns — what it IS
public class Customer { }
public class OrderProcessor { }
public class DiscountValidator { }

// Methods: verbs — what it DOES
public void save() { }
public Order processOrder() { }
public boolean isValid() { }

Functions Should Be Small

One Level of Abstraction Per Function

// BAD — mixes business logic with raw JDBC details in the same method
public void processOrder(Order order) {
    validateOrder(order);   // high level

    Connection conn = DriverManager.getConnection(url);   // low level
    PreparedStatement stmt = conn.prepareStatement(
        "INSERT INTO orders (id, total) VALUES (?, ?)");
    stmt.setLong(1, order.getId());
    stmt.setDouble(2, order.getTotal());
    stmt.executeUpdate();

    sendConfirmation(order);   // high level again
}

// GOOD — every line in this method is at the same level of abstraction
public void processOrder(Order order) {
    validateOrder(order);
    saveOrder(order);
    sendConfirmation(order);
}

private void saveOrder(Order order) {
    orderRepository.save(order);
}

Do One Thing

// BAD — the name itself admits the function does multiple things
public void registerCustomerAndSendEmailAndLogActivity(Customer customer) { }

// GOOD — one coordinating method, each concern its own focused function
public void registerCustomer(Customer customer) {
    validate(customer);
    save(customer);
    notifyCustomer(customer);
    auditRegistration(customer);
}

private void validate(Customer customer) { /* validation only */ }
private void save(Customer customer) { /* persistence only */ }
private void notifyCustomer(Customer customer) { /* notification only */ }
private void auditRegistration(Customer customer) { /* logging only */ }

Function Arguments

// Ideal: zero arguments (niladic)
public void run() { }

// Good: one argument (monadic)
public void process(Order order) { }

// Acceptable: two arguments (dyadic)
public BigDecimal calculateTax(BigDecimal subtotal, String region) { }

// AVOID — three or more positional arguments
public void registerCustomer(String name, String email,
                              String address, String phone) { }

// GOOD — group related arguments into a record
public record CustomerRegistration(String name, String email,
                                     String address, String phone) { }
public void registerCustomer(CustomerRegistration registration) { }

// Avoid flag (boolean) arguments — the call site doesn't tell you what "true" means
// BAD
public void renderReport(boolean isSummary) { }
renderReport(true);   // true... meaning what, exactly?

// GOOD — two named methods, self-documenting at the call site
public void renderSummaryReport() { }
public void renderDetailedReport() { }

Avoid Hidden Side Effects

// BAD — a method named "check" that also silently starts a session
public boolean isAuthenticated(String email, String hashedPassword) {
    Customer customer = customerGateway.findByEmail(email);
    if (customer != null && passwordEncoder.matches(hashedPassword, customer.getPasswordHash())) {
        Session.initialize();   // hidden side effect — the name promised a yes/no answer, not a session
        return true;
    }
    return false;
}

// GOOD — explicit and predictable: one function answers, the caller decides what to do
public boolean isAuthenticated(String email, String rawPassword) {
    Customer customer = customerRepository.findByEmail(email);
    return customer != null && passwordEncoder.matches(rawPassword, customer.getPasswordHash());
}

public void login(String email, String rawPassword) {
    if (isAuthenticated(email, rawPassword)) {
        sessionManager.initialize();   // explicit, at the call site that actually decides to do it
    }
}

Comments: When and When Not

Bad Comments

// BAD — redundant, restates the next line
// increment i
i++;

// BAD — noise, adds nothing a reader doesn't already know
/** Default constructor */
public Customer() { }

// BAD — commented-out code, a Git history already tracks old versions
// customerService.oldMethod();

// BAD — actively misleading; the comment lies about what the code does
// Returns the customer's loyalty points balance in cents
public int getLoyaltyPoints() {
    return points;   // actually whole points, not cents!
}

Good Comments

// GOOD — explains WHY, which the code can't show on its own
// Insertion sort here, not the default: this list is nearly sorted
// and small (< 20 items), so insertion sort is measurably faster

// GOOD — warns of a real consequence a reader needs before running it
// Warning: this integration test suite takes ~15 minutes (Testcontainers startup)

// GOOD — clarifies genuinely obscure code, doesn't restate obvious code
// Format: YYMMDD + 4-digit sequence number
String orderId = dateFormat.format(date) + sequence;

Error Handling — Null and Optional

// BAD — returning null forces every caller to remember to check
public List<Order> getOrdersForCustomer(Long customerId) {
    if (noOrdersFound) {
        return null;
    }
    return orders;
}

// GOOD — an empty collection is a value, not a special case to remember
public List<Order> getOrdersForCustomer(Long customerId) {
    if (noOrdersFound) {
        return Collections.emptyList();
    }
    return orders;
}

// GOOD — Optional makes "might not exist" part of the method's type
public Optional<Customer> findById(Long id) {
    return Optional.ofNullable(customerMap.get(id));
}

// GOOD — fail loudly and immediately at the boundary, not silently later
public BigDecimal calculateDistance(Point origin, Point destination) {
    Objects.requireNonNull(origin, "origin must not be null");
    Objects.requireNonNull(destination, "destination must not be null");
    // safe to proceed
}

DRY — Don't Repeat Yourself

// BAD — the same validation logic duplicated across two unrelated methods
public void validateCustomer(Customer customer) {
    if (customer.getFullName() == null || customer.getFullName().isEmpty()) {
        throw new ValidationException("Name required");
    }
    if (customer.getFullName().length() > 100) {
        throw new ValidationException("Name too long");
    }
}

public void validateProduct(Product product) {
    if (product.getName() == null || product.getName().isEmpty()) {
        throw new ValidationException("Name required");
    }
    if (product.getName().length() > 100) {
        throw new ValidationException("Name too long");
    }
}

// BETTER — extract the shared logic once
private void validateName(String name, String fieldName) {
    if (name == null || name.isEmpty()) {
        throw new ValidationException(fieldName + " required");
    }
    if (name.length() > 100) {
        throw new ValidationException(fieldName + " too long");
    }
}

public record CustomerRequest(
    @NotBlank(message = "Name required")
    @Size(max = 100, message = "Name too long")
    String fullName
) { }

@PostMapping
public ResponseEntity<Customer> create(@Valid @RequestBody CustomerRequest request) { ... }

Code Organization — the Newspaper Metaphor

// A class read top to bottom like a newspaper article:
// - Headline (class name) tells you what it's about
// - High-level summary first (public methods)
// - Details come later (private methods)

public class OrderService {

    // PUBLIC — the "headline": high-level operations a caller reasons about
    public Order createOrder(OrderRequest request) {
        validate(request);
        Order order = buildOrder(request);
        return save(order);
    }

    public void cancelOrder(Long orderId) {
        Order order = findOrder(orderId);
        markAsCancelled(order);
        notifyCustomer(order);
    }

    // PRIVATE — the "body": implementation details, only relevant once
    // you've decided you care how createOrder() actually works
    private void validate(OrderRequest request) { ... }
    private Order buildOrder(OrderRequest request) { ... }
    private Order save(Order order) { ... }
    private Order findOrder(Long id) { ... }
    private void markAsCancelled(Order order) { ... }
    private void notifyCustomer(Order order) { ... }
}

Best Practices and Common Pitfalls

Interview Questions