# Java Coding Standard

> This skill should be activated when reviewing Java code or enforcing coding standards in Spring Boot services. It covers naming conventions, immutability patterns, Optional usage, streams, and exception handling.

- Skill: `kumaran-is/java-coding-standard` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add kumaran-is/java-coding-standard`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kumaran-is/java-coding-standard/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kumaran-is (https://skillmd.com/u/kumaran-is)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kumaran-is/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.