java-coding-standards

Java Coding Standards

Standards for readable, maintainable Java (17+) code in Spring Boot services.

When to Activate

• Writing or reviewing Java code in Spring Boot projects
• Enforcing naming, immutability, or exception handling conventions
• Working with records, sealed classes, or pattern matching (Java 17+)
• Reviewing use of Optional, streams, or generics
• Structuring packages and project layout

Core Principles

• Prefer clarity over cleverness
• Immutable by default; minimize shared mutable state
• Fail fast with meaningful exceptions
• Consistent naming and package structure

Naming

// PASS: Classes/Records: PascalCase
public class MarketService {}
public record Money(BigDecimal amount, Currency currency) {}

// PASS: Methods/fields: camelCase
private final MarketRepository marketRepository;
public Market findBySlug(String slug) {}

// PASS: Constants: UPPER_SNAKE_CASE
private static final int MAX_PAGE_SIZE = 100;

Immutability

// PASS: Favor records and final fields
public record MarketDto(Long id, String name, MarketStatus status) {}

public class Market {
  private final Long id;
  private final String name;
  // getters only, no setters
}

Optional Usage

// PASS: Return Optional from find* methods
Optional<Market> market = marketRepository.findBySlug(slug);

// PASS: Map/flatMap instead of get()
return market
    .map(MarketResponse::from)
    .orElseThrow(() -> new EntityNotFoundException("Market not found"));

Streams Best Practices

// PASS: Use streams for transformations, keep pipelines short
List<String> names = markets.stream()
    .map(Market::name)
    .filter(Objects::nonNull)
    .toList();

// FAIL: Avoid complex nested streams; prefer loops for clarity

Exceptions

• Use unchecked exceptions for domain errors; wrap technical exceptions with context
• Create domain-specific exceptions (e.g., MarketNotFoundException)
• Avoid broad catch (Exception ex) unless rethrowing/logging centrally