java-coding-standard

Iron Law: Always load the java-spring-api skill and consult Spring MCP before writing Java code; never generate Spring WebFlux patterns from memory.

Java Coding Standards

Standards for readable, maintainable Java (21+) code in Spring Boot Reactive Web Flux services.

Core Principles

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

Key Rules

| Rule | Standard | |------|----------| | Naming | Classes: PascalCase, methods/fields: camelCase, constants: UPPER_SNAKE_CASE | | Immutability | Favor records and final fields; getters only, no setters. Exception: R2DBC entities require setters for framework binding | | Optional | Return Optional from find* methods; use map/flatMap, never .get(). In reactive code, Mono<T> replaces Optional<T> — use switchIfEmpty() instead | | Streams | Short pipelines for transforms; prefer loops for complex logic | | Exceptions | Unchecked domain exceptions; avoid broad catch (Exception) | | Generics | No raw types; prefer bounded generics for reusable utilities | | Null handling | @NonNull by default; Bean Validation on inputs | | Logging | SLF4J with structured key=value pairs | | Testing | JUnit 5 + AssertJ + Mockito + WebTestClient for reactive; deterministic, no sleeps |

Project Structure

src/main/java/com/company/<service>/
  config/ → controller/ → service/ → repository/ → model/entity/ → model/dto/ → exception/
src/main/resources/application.yml
src/test/java/... (mirrors main)

Code Examples & Detailed Patterns

For naming examples, immutability patterns, Optional usage, streams, exception handling, generics, logging, formatting, code smells, and testing expectations, Read reference/java-standards-examples.md.

Remember: Keep code intentional, typed, and observable. Optimize for maintainability over micro-optimizations unless proven necessary.

Error Handling

Checked vs unchecked exceptions: Use unchecked (RuntimeException subclasses) for programming errors. Use checked exceptions only for recoverable conditions the caller must handle.

Optional misuse: Never call .get() without .isPresent() or use .orElseThrow(). Prefer map/flatMap chains.