Java Coding Standards

1---2name: java-coding-standards3description: "Java coding standards for Spring Boot services: naming, immutability, Optional usage, streams, exceptions, generics, and project layout."4origin: ECC5---6 7# Java Coding Standards8 9Standards for readable, maintainable Java (17+) code in Spring Boot services.10 11## When to Activate12 13- Writing or reviewing Java code in Spring Boot projects14- Enforcing naming, immutability, or exception handling conventions15- Working with records, sealed classes, or pattern matching (Java 17+)16- Reviewing use of Optional, streams, or generics17- Structuring packages and project layout18 19## Core Principles20 21- Prefer clarity over cleverness22- Immutable by default; minimize shared mutable state23- Fail fast with meaningful exceptions24- Consistent naming and package structure25 26## Naming27 28```java29// PASS: Classes/Records: PascalCase30public class MarketService {}31public record Money(BigDecimal amount, Currency currency) {}32 33// PASS: Methods/fields: camelCase34private final MarketRepository marketRepository;35public Market findBySlug(String slug) {}36 37// PASS: Constants: UPPER_SNAKE_CASE38private static final int MAX_PAGE_SIZE = 100;39```40 41## Immutability42 43```java44// PASS: Favor records and final fields45public record MarketDto(Long id, String name, MarketStatus status) {}46 47public class Market {48  private final Long id;49  private final String name;50  // getters only, no setters51}52```53 54## Optional Usage55 56```java57// PASS: Return Optional from find* methods58Optional<Market> market = marketRepository.findBySlug(slug);59 60// PASS: Map/flatMap instead of get()61return market62    .map(MarketResponse::from)63    .orElseThrow(() -> new EntityNotFoundException("Market not found"));64```65 66## Streams Best Practices67 68```java69// PASS: Use streams for transformations, keep pipelines short70List<String> names = markets.stream()71    .map(Market::name)72    .filter(Objects::nonNull)73    .toList();74 75// FAIL: Avoid complex nested streams; prefer loops for clarity76```77 78## Exceptions79 80- Use unchecked exceptions for domain errors; wrap technical exceptions with context81- Create domain-specific exceptions (e.g., `MarketNotFoundException`)82- Avoid broad `catch (Exception ex)` unless rethrowing/logging centrally83 84```java85throw new MarketNotFoundException(slug);86```87 88## Generics and Type Safety89 90- Avoid raw types; declare generic parameters91- Prefer bounded generics for reusable utilities92 93```java94public <T extends Identifiable> Map<Long, T> indexById(Collection<T> items) { ... }95```96 97## Project Structure (Maven/Gradle)98 99```100src/main/java/com/example/app/101  config/102  controller/103  service/104  repository/105  domain/106  dto/107  util/108src/main/resources/109  application.yml110src/test/java/... (mirrors main)111```112 113## Formatting and Style114 115- Use 2 or 4 spaces consistently (project standard)116- One public top-level type per file117- Keep methods short and focused; extract helpers118- Order members: constants, fields, constructors, public methods, protected, private119 120## Code Smells to Avoid121 122- Long parameter lists → use DTO/builders123- Deep nesting → early returns124- Magic numbers → named constants125- Static mutable state → prefer dependency injection126- Silent catch blocks → log and act or rethrow127 128## Logging129 130```java131private static final Logger log = LoggerFactory.getLogger(MarketService.class);132log.info("fetch_market slug={}", slug);133log.error("failed_fetch_market slug={}", slug, ex);134```135 136## Null Handling137 138- Accept `@Nullable` only when unavoidable; otherwise use `@NonNull`139- Use Bean Validation (`@NotNull`, `@NotBlank`) on inputs140 141## Testing Expectations142 143- JUnit 5 + AssertJ for fluent assertions144- Mockito for mocking; avoid partial mocks where possible145- Favor deterministic tests; no hidden sleeps146 147**Remember**: Keep code intentional, typed, and observable. Optimize for maintainability over micro-optimizations unless proven necessary.