Java Code Conventions

Why Code Conventions Matter

A convention's value isn't the specific choice — 4 spaces vs 2, braces on the same line or the next — it's that every developer stops spending attention on it at all. Without one, every file silently tells the reader "a different person with different habits wrote this," which is cognitive overhead spent on formatting instead of on understanding what the code actually does.

// BEFORE — technically correct, three different naming styles in one file
public class order_Service {
    public Order Get_order(int OrderId) { ... }
    private boolean checkstock;
}
// Every reader has to first decode "what does this project's style even
// mean" before they can think about the logic at all.

// AFTER — one convention, applied consistently
public class OrderService {
    public Order getOrder(long orderId) { ... }
    private boolean stockAvailable;
}

Naming Conventions

Classes and Interfaces

// Classes: PascalCase, nouns
public class CustomerAccount { }
public class OrderProcessingService { }

// Interfaces: PascalCase, often capabilities or adjectives
public interface PaymentProcessor { }
public interface Serializable { }

// Abstract classes: PascalCase, often prefixed with Abstract
public abstract class AbstractRepository { }

// Exceptions: PascalCase, suffixed with Exception
public class InsufficientInventoryException extends RuntimeException { }

Methods

// Methods: camelCase, verbs or verb phrases
public BigDecimal calculateTotal() { }
public Order findById(Long id) { }
public void sendConfirmationEmail() { }

// Boolean-returning methods: is, has, can, should
public boolean isActive() { }
public boolean hasDiscount() { }
public boolean canCancel() { }

// Static factory methods
public static Customer of(String email) { }
public static Order createDraft() { }

Variables and Constants

// Variables: camelCase, descriptive
String customerEmail = "jane@shop.com";
List<Order> pendingOrders = new ArrayList<>();

// Constants: SCREAMING_SNAKE_CASE
public static final int MAX_RETRY_COUNT = 3;
private static final Logger LOGGER = LoggerFactory.getLogger(OrderService.class);

// Single-letter names: acceptable only for loop counters, nowhere else
for (int i = 0; i < items.size(); i++) { }   // fine
int x = calculateTotal();                     // not fine — says nothing

Packages

// Packages: all lowercase, reverse domain name, no underscores
package com.shop.orderservice;
package com.shop.orderservice.pricing;

Package Organization — By Layer vs By Feature

The default most tutorials teach is packaging by technical layer. It works fine for a small service, and quietly gets worse as the codebase grows.

// Package-by-layer — the common default
com.shop.orderservice
├── controller     // OrderController, CustomerController, ...
├── service        // OrderService, PricingService, ...
├── repository     // OrderRepository, CustomerRepository, ...
├── model          // Order, Customer, OrderItem, ...
└── dto            // OrderResponse, CustomerRequest, ...

// Package-by-feature — groups everything a single feature needs together
com.shop.orderservice
├── order
│   ├── OrderController
│   ├── OrderService
│   ├── OrderRepository
│   └── Order
├── pricing
│   ├── PricingService
│   └── DiscountRule
└── customer
    ├── CustomerController
    ├── CustomerService
    └── Customer

Formatting

Braces and Indentation

// Opening brace on the same line (K&R style) — the Java convention
public class Example {
    public void method() {
        if (condition) {
            // ...
        } else {
            // ...
        }
    }
}

// Always use braces, even for a single statement
// GOOD
if (valid) {
    process();
}
// AVOID — adding a second statement later without noticing the missing
// braces is a real, recurring source of bugs
if (valid)
    process();

Line Length and Wrapping

// Keep lines under 120 characters (100 is a common team default)
List<Order> orders = orderRepository
        .findByStatusAndCreatedAtAfter(
                OrderStatus.PENDING,
                Instant.now().minus(30, ChronoUnit.DAYS)
        );

List<String> activeEmails = customers.stream()
        .filter(Customer::isActive)
        .map(Customer::getEmail)
        .sorted()
        .toList();

Blank Lines

public class OrderService {

    private final OrderRepository orderRepository;
    private final PaymentService paymentService;
                                              // blank line after fields
    public OrderService(OrderRepository repo, PaymentService payment) {
        this.orderRepository = repo;
        this.paymentService = payment;
    }
                                              // blank line between methods
    public Order createOrder(OrderRequest request) {
        Order order = orderRepository.save(new Order(request));
                                              // blank line for logical separation
        paymentService.charge(order);
        return order;
    }
}

Class Structure — Recommended Member Order

public class WellOrganizedService {

    // 1. Static constants
    private static final Logger LOGGER = LoggerFactory.getLogger(WellOrganizedService.class);

    // 2. Instance fields
    private final OrderRepository orderRepository;

    // 3. Constructors
    public WellOrganizedService(OrderRepository orderRepository) {
        this.orderRepository = orderRepository;
    }

    // 4. Static factory methods
    public static WellOrganizedService withDefaults() { ... }

    // 5. Public methods — the public API, in the order a reader would use them
    public Order createOrder(OrderRequest request) { ... }

    // 6. Package-private / protected methods
    void internalMethod() { ... }

    // 7. Private helper methods
    private void validate(OrderRequest request) { ... }

    // 8. Nested classes
    private static class InternalHelper { }
}

Import Statements

// Order: java.*, jakarta.*, third-party, project packages
import java.util.List;

import jakarta.validation.Valid;

import org.springframework.stereotype.Service;

import com.shop.orderservice.model.Order;

// Avoid wildcard imports — hides what's actually used and silently
// changes meaning if a new class is later added to that package
import java.util.*;   // avoid

// Static imports: fine for test assertions and true constants, not
// for regular business logic — it hides where a method actually lives
import static org.junit.jupiter.api.Assertions.*;   // OK in tests

Comments and Documentation

Javadoc

/**
 * Service for managing customer orders.
 *
 * @since 1.0
 */
public class OrderService {

    /**
     * Finds an order by its unique identifier.
     *
     * @param id the order's unique identifier
     * @return the order if found
     * @throws OrderNotFoundException if no order exists with the given id
     */
    public Order findById(Long id) { ... }
}

Inline Comments

// GOOD — explains WHY, which the code itself can't show
// Retry up to 3 times: the payment gateway has occasional transient timeouts
for (int attempt = 0; attempt < 3; attempt++) { ... }

// BAD — restates what the next line already says
// increment the counter
counter++;

// TODO comments should reference a tracked ticket, not float unowned
// TODO: implement caching (ORD-1234)

Modern Java Style

// var — for obviously-inferable types (Java 10+)
var orders = new ArrayList<Order>();
// Avoid var when the right-hand side doesn't make the type obvious at a glance:
var result = orderService.process(request);   // process() returns... what? Prefer explicit here.

// records — the site's own convention: every DTO is a record
public record OrderSummary(Long id, BigDecimal total, OrderStatus status) { }

// text blocks — multi-line strings (Java 15+)
String json = """
    {"status": "CREATED"}
    """;

// switch expressions (Java 14+)
String label = switch (status) {
    case ACTIVE -> "Active";
    case PENDING -> "Awaiting approval";
};

// pattern matching for switch + record patterns (Java 21+) —
// destructure a sealed hierarchy directly in the switch itself
sealed interface PaymentResult permits Success, Declined {}
record Success(String transactionId) implements PaymentResult {}
record Declined(String reason) implements PaymentResult {}

String message = switch (result) {
    case Success(String txId) -> "Payment succeeded: " + txId;
    case Declined(String reason)  -> "Payment declined: " + reason;
    // sealed + exhaustive switch — no default needed, and the compiler
    // errors if a new permitted type is added and this switch isn't updated
};

Enforcing Conventions Automatically

A convention that lives only in a wiki page gets followed inconsistently. The reliable version is enforced by tooling in CI — covered in full in Code Quality Tools (Checkstyle, PMD, Spotless) and CI/CD Basics. The short version here: .editorconfig for cross-IDE basics, Checkstyle for naming rules like the ones on this page, and Spotless for auto-fixable formatting — see those pages for the actual configuration.

Best Practices and Common Pitfalls

Interview Questions