java-coding

Java Coding Standards

Naming Conventions

Element	Convention	Example
Package	lowercase, reverse domain	com.yourorg.order.service
Class	PascalCase, noun	OrderService, PaymentGateway
Interface	PascalCase, adjective or noun	Payable, OrderRepository
Method	camelCase, verb	createOrder, findById
Constant	UPPER_SNAKE	MAX_RETRY_COUNT
Variable	camelCase	orderId, totalAmount

Modern Java Features (17+)

// Records for DTOs and value objects
public record OrderResponse(Long id, String customerId, BigDecimal total, OrderStatus status) {}

// Sealed classes for domain hierarchies
public sealed interface PaymentResult permits PaymentSuccess, PaymentFailure, PaymentPending {}
public record PaymentSuccess(String transactionId) implements PaymentResult {}
public record PaymentFailure(String reason) implements PaymentResult {}

// Pattern matching for instanceof
if (result instanceof PaymentSuccess success) {
    log.info("Payment completed: {}", success.transactionId());
}

// Text blocks for SQL/JSON
var query = """
    SELECT o.id, o.customer_id, o.total
    FROM orders o
    WHERE o.status = :status
    """;

Optional

• Return Optional<T> from finder methods that may not find a result
• Never use Optional as a method parameter or field
• Prefer orElseThrow() with specific exception over get()
• Use map/flatMap for chaining, not isPresent/get

// Good
Order order = repository.findById(id)
    .orElseThrow(() -> new OrderNotFoundException(id));

// Bad
Optional<Order> opt = repository.findById(id);
if (opt.isPresent()) { return opt.get(); }

Streams

• Use for transformations and filtering, not side effects
• Prefer method references: items.stream().map(Item::name)
• Use Collectors.toUnmodifiableList() for immutable results
• Don't use parallel streams unless measured and necessary

Error Handling

• Use checked exceptions for recoverable conditions only
• Use unchecked (runtime) exceptions for programming errors
• Always provide context in exception messages
• Use custom domain exceptions: OrderNotFoundException, InsufficientStockException
• Never catch Exception or Throwable broadly

Dependency Injection

• Constructor injection only — never field injection
• Use final fields for all injected dependencies
• Max 5 constructor parameters — extract a service if more