Java Coding Standards

Java Coding Standards

A comprehensive collection of Java coding standards and best practices. Designed for AI agents and LLMs to generate high-quality, idiomatic, and maintainable Java code.

Categories

Anti-Patterns [CRITICAL]

Recognize and eliminate recurring Java anti-patterns that erode correctness, encapsulation, and readability.

Resource Management [CRITICAL]

Acquire and release JVM and I/O resources deterministically, without leaks or hand-written cleanup.

Concurrency [HIGH]

Coordinate shared state and background work safely across threads and virtual threads.

API Design [HIGH]

Shape public class and method surfaces so they are hard to misuse.

Error Handling [HIGH]

Propagate, translate, and represent failures explicitly instead of hiding or discarding them.

Immutability [HIGH]

Default to immutable state and defensive construction to eliminate whole classes of bugs.

Object-Oriented Design [HIGH]

Apply core object-oriented design principles for maintainable, extensible class hierarchies.

Sealed Types & Pattern Matching [HIGH]

Model closed sets of variants with sealed types and exhaustive pattern matching.

Javadoc [HIGH]

Document public API contracts precisely, without narrating the signature.

Records [HIGH]

Use records correctly as immutable, validated data carriers.

Reflection & Serialization [HIGH]

Keep reflection and serialization at the edges of the system, configured explicitly.

Modules [HIGH]

Manage module and package boundaries deliberately across Gradle and JPMS.

Collections & Streams [MEDIUM]

Use the Collections and Stream APIs idiomatically, without redundant materialization or hidden side effects.

Generics [MEDIUM]

Use Java generics safely, without raw types or unchecked casts.

Nullability [MEDIUM]

Represent absence explicitly with Optional at API boundaries, never as a field or parameter type.

Performance [MEDIUM]

Apply measured, targeted performance techniques instead of premature optimization.

Naming [MEDIUM]

Choose names that reveal intention and avoid encoding type or scope.

Quick Reference

Anti-Patterns

public void processMessage(Message message) {
    try {
        handler.handle(message);
    } catch (MessageProcessingException e) { // specific, documented, recoverable
        log.error("Failed to process message {}", message.id(), e);
        deadLetterQueue.send(message);
    }
    // an Error propagates uncaught, as it should
}

Resource Management

public String readFirstLine(Path path) throws IOException {
    try (BufferedReader reader = Files.newBufferedReader(path)) {
        return reader.readLine(); // reader.close() runs on every exit path
    }
}

Concurrency

try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
    for (Request request : requests) {
        executor.submit(() -> handle(request)); // one virtual thread per task
    }
} // close() awaits completion of submitted tasks

API Design

public static final class Builder {
    private final String url;
    private final String method;
    private int timeoutMs = 3000;

    public Builder timeoutMs(int timeoutMs) { this.timeoutMs = timeoutMs; return this; }
    public HttpRequest build() { return new HttpRequest(this); }
}

HttpRequest request = HttpRequest.builder("https://api.example.com", "GET")
    .timeoutMs(5000)
    .build();

Error Handling

public Either<ValidationError, Order> validate(OrderRequest request) {
    if (request.items().isEmpty()) {
        return Either.left(new ValidationError("order must have at least one item"));
    }
    return Either.right(new Order(request));
}

return validator.validate(request)
    .map(orderRepository::save)
    .fold(error -> ResponseEntity.badRequest().body(error.message()),
          order -> ResponseEntity.ok(order));

Immutability

public record Money(BigDecimal amount, String currency) {
    public Money {
        Objects.requireNonNull(amount, "amount");
        Objects.requireNonNull(currency, "currency");
        if (amount.scale() > 2) {
            throw new IllegalArgumentException("amount must have at most 2 decimal places");
        }
    }
}

Object-Oriented Design

public class InstrumentedList<E> {
    private final List<E> delegate;
    private int addCount = 0;

    public boolean add(E e) {
        addCount++;
        return delegate.add(e); // composes List, independent of its internals
    }
}

Sealed Types & Pattern Matching

sealed interface Shape permits Circle, Rectangle, Triangle {}

double area(Shape shape) {
    return switch (shape) {
        case Circle c -> Math.PI * c.radius() * c.radius();
        case Rectangle r -> r.width() * r.height();
        case Triangle t -> 0.5 * t.base() * t.height();
        // No default: the compiler verifies every permitted Shape is covered.
    };
}

Javadoc

/**
 * Returns the sum of {@link Order#total()} across all given orders.
 *
 * @param orders the orders to total; must not be {@code null} or contain {@code null}
 * @return the combined total, or {@link BigDecimal#ZERO} if {@code orders} is empty
 */
public BigDecimal totalValue(List<Order> orders) {
    return orders.stream().map(Order::total).reduce(BigDecimal.ZERO, BigDecimal::add);
}

Records

public record Percentage(int value) {
    public Percentage {
        if (value < 0 || value > 100) {
            throw new IllegalArgumentException("value must be 0-100, was " + value);
        }
    }
}

Percentage discount = new Percentage(150); // throws IllegalArgumentException immediately

Reflection & Serialization

public static final ObjectMapper DEFAULT = JsonMapper.builder()
        .addModule(new JavaTimeModule())
        .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, true)
        .configure(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, false)
        .serializationInclusion(JsonInclude.Include.NON_ABSENT)
        .build();

Modules

module com.example.billing {
    exports com.example.billing.api;

    requires java.sql;
    // com.example.billing.internal is not exported — usable inside the
    // module, invisible outside it
}

Collections & Streams

public List<String> activeAdminEmails(List<User> users) {
    return users.stream()
        .filter(User::isActive)
        .filter(user -> user.getRole() == Role.ADMIN)
        .map(User::getEmail)
        .map(String::toLowerCase)
        .toList();
}

Generics

// source only produces T (extends), destination only consumes T (super)
public static <T> void copy(List<? extends T> source, List<? super T> destination) {
    for (T item : source) {
        destination.add(item);
    }
}

Nullability

public Optional<User> findById(Long id) {
    return Optional.ofNullable(usersById.get(id));
}

repository.findById(id)
    .map(User::getEmail)
    .ifPresentOrElse(this::sendWelcomeEmail, () -> log.warn("No user found for id {}", id));

Performance

public String buildCsvLine(List<String> fields) {
    StringBuilder line = new StringBuilder();
    for (String field : fields) {
        line.append(field).append(','); // amortized O(1) per call
    }
    return line.toString();
}

Naming

public class SubscriptionRenewalQueue {
    private final List<Subscription> pendingRenewals = new ArrayList<>();

    public void enqueueIfEligible(Subscription subscription, RenewalStatus status) {
        if (status == RenewalStatus.ELIGIBLE) {
            pendingRenewals.add(subscription);
        }
    }
}

See Also

• java-testing - Test-writing best practices for JUnit 5, AssertJ, Mockito, and Testcontainers
• java-tooling - Build, static analysis, CI quality gate, dependency management, and formatting rules