java-idioms

Java Idioms and Patterns

Java rewards clarity, type safety, and robust ecosystem tooling. Modern Java (17+ LTS) favors records, sealed classes, and pattern matching. Idiomatic Java = clean, readable, framework-aware.

Scope: Java coding idioms. Test naming: .agents/rules/testing-strategy.md. Logging: @.agents/skills/logging-implementation/SKILL.md.

Modern Java Features (17+ LTS)

1. Records for immutable data carriers:

   // ✅ Concise, immutable, auto-generated equals/hashCode/toString
   public record CreateTaskRequest(String title, Priority priority) {}
   
   // ❌ Verbose boilerplate POJO
   public class CreateTaskRequest { /* getters, setters, equals, hashCode... */ }
   

2. Sealed classes for constrained hierarchies:

   public sealed interface TaskResult permits Success, Failure, Pending {}
   public record Success(Task task) implements TaskResult {}
   public record Failure(String reason) implements TaskResult {}
   public record Pending(String taskId) implements TaskResult {}
   

3. Pattern matching with switch:

   return switch (result) {
       case Success(var task) -> ResponseEntity.ok(task);
       case Failure(var reason) -> ResponseEntity.badRequest().body(reason);
       case Pending(var id) -> ResponseEntity.accepted().body(id);
   };
   

4. Text blocks for queries and templates:

   String query = """
       SELECT t.id, t.title, t.priority
       FROM tasks t
       WHERE t.user_id = ?
       ORDER BY t.created_at DESC
       """;
   

5. Virtual threads (21+) for I/O-bound work:

   try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
       executor.submit(() -> fetchUser(userId));
       executor.submit(() -> fetchTasks(userId));
   }
   

Error Handling

1. Domain exception hierarchies — never raw Exception:

   public abstract class DomainException extends RuntimeException {
       protected DomainException(String message) { super(message); }
   }
   
   public class NotFoundException extends DomainException {
       private final String resource;
       private final String resourceId;
       public NotFoundException(String resource, String resourceId) {
           super(String.format("%s '%s' not found", resource, resourceId));
           this.resource = resource;
           this.resourceId = resourceId;
       }
   }
   

2. Never catch Exception broadly — catch specific exceptions. Never swallow exceptions silently.

3. Optional for nullable returns — never for parameters:

   // ✅ Return type
   public Optional<Task> findById(String id) { ... }
   
   // ❌ Parameter — use overloading or @Nullable instead
   public void process(Optional<String> filter) { ... }
   

Interfaces and DI

1. Program to interfaces, inject via constructor:

   // ✅ Interface in consumer package
   public interface TaskStorage {
       Task getById(String id);
       void save(Task task);
   }
   
   // ✅ Constructor injection (Spring auto-wires)
   @Service
   public class TaskService {
       private final TaskStorage storage;
       public TaskService(TaskStorage storage) { this.storage = storage; }
   }
   

2. Prefer constructor injection over @Autowired field injection. No field injection — ever.

Naming

1. PascalCase for classes, interfaces, enums, records.
2. camelCase for methods, fields, local variables.
3. UPPER_SNAKE_CASE for constants (static final).
4. No Hungarian notation. TaskService not ITaskService. userId not strUserId.
5. Package names: lowercase, no underscores. com.example.task not com.example.task_management.

Testing

Test naming, pyramid: .agents/rules/testing-strategy.md. Java-specific tooling below.

1. JUnit 5 + AssertJ:

   @Test
   void calculateDiscount_returnsZero_whenNoItems() {
       var result = calculator.calculateDiscount(List.of(), coupon);
       assertThat(result).isEqualTo(0.0);
   }
   

2. @ParameterizedTest for table-driven tests:

   @ParameterizedTest
   @CsvSource({"low,1", "medium,5", "high,10"})
   void priorityScore_mapsCorrectly(String priority, int expected) {
       assertThat(Priority.score(priority)).isEqualTo(expected);
   }
   

3. Mockito for mocking — never PowerMock:

   @ExtendWith(MockitoExtension.class)
   class TaskServiceTest {
       @Mock TaskStorage storage;
       @InjectMocks TaskService service;
   }
   

4. TestContainers for integration tests — real DB, no in-memory substitutes for critical paths.

Formatting and Static Analysis

Must pass zero warnings/errors before commit. See .agents/rules/code-idioms-and-conventions.md.

Tool	Purpose	Command
google-java-format	Canonical formatting	google-java-format --replace src/**/*.java
SpotBugs	Bug detection	mvn spotbugs:check or gradle spotbugsMain
Error Prone	Compile-time bug detection	Compiler plugin
Checkstyle	Style enforcement	mvn checkstyle:check
SonarQube	Comprehensive analysis	CI integration
OWASP Dependency-Check	CVE scanning	mvn dependency-check:check

Related

• Code Idioms and Conventions .agents/rules/code-idioms-and-conventions.md
• Testing Strategy .agents/rules/testing-strategy.md
• Error Handling Principles .agents/rules/error-handling-principles.md
• Dependency Management Principles @.agents/rules/dependency-management-principles.md
• Logging Implementation @.agents/skills/logging-implementation/SKILL.md