Cursor rule

1---
2paths:
3  - "**/*.java"
4---
5# Java Coding Style
6 
7> This file extends [common/coding-style.md](../common/coding-style.md) with Java-specific content.
8 
9## Formatting
10 
11- **google-java-format** or **Checkstyle** (Google or Sun style) for enforcement
12- One public top-level type per file
13- Consistent indent: 2 or 4 spaces (match project standard)
14- Member order: constants, fields, constructors, public methods, protected, private
15 
16## Immutability
17 
18- Prefer `record` for value types (Java 16+)
19- Mark fields `final` by default — use mutable state only when required
20- Return defensive copies from public APIs: `List.copyOf()`, `Map.copyOf()`, `Set.copyOf()`
21- Copy-on-write: return new instances rather than mutating existing ones
22 
23```java
24// GOOD — immutable value type
25public record OrderSummary(Long id, String customerName, BigDecimal total) {}
26 
27// GOOD — final fields, no setters
28public class Order {
29    private final Long id;
30    private final List<LineItem> items;
31 
32    public List<LineItem> getItems() {
33        return List.copyOf(items);
34    }
35}
36```
37 
38## Naming
39 
40Follow standard Java conventions:
41- `PascalCase` for classes, interfaces, records, enums
42- `camelCase` for methods, fields, parameters, local variables
43- `SCREAMING_SNAKE_CASE` for `static final` constants
44- Packages: all lowercase, reverse domain (`com.example.app.service`)
45 
46## Modern Java Features
47 
48Use modern language features where they improve clarity:
49- **Records** for DTOs and value types (Java 16+)
50- **Sealed classes** for closed type hierarchies (Java 17+)
51- **Pattern matching** with `instanceof` — no explicit cast (Java 16+)
52- **Text blocks** for multi-line strings — SQL, JSON templates (Java 15+)
53- **Switch expressions** with arrow syntax (Java 14+)
54- **Pattern matching in switch** — exhaustive sealed type handling (Java 21+)
55 
56```java
57// Pattern matching instanceof
58if (shape instanceof Circle c) {
59    return Math.PI * c.radius() * c.radius();
60}
61 
62// Sealed type hierarchy
63public sealed interface PaymentMethod permits CreditCard, BankTransfer, Wallet {}
64 
65// Switch expression
66String label = switch (status) {
67    case ACTIVE -> "Active";
68    case SUSPENDED -> "Suspended";
69    case CLOSED -> "Closed";
70};
71```
72 
73## Optional Usage
74 
75- Return `Optional<T>` from finder methods that may have no result
76- Use `map()`, `flatMap()`, `orElseThrow()` — never call `get()` without `isPresent()`
77- Never use `Optional` as a field type or method parameter
78 
79```java
80// GOOD
81return repository.findById(id)
82    .map(ResponseDto::from)
83    .orElseThrow(() -> new OrderNotFoundException(id));
84 
85// BAD — Optional as parameter
86public void process(Optional<String> name) {}
87```
88 
89## Error Handling
90 
91- Prefer unchecked exceptions for domain errors
92- Create domain-specific exceptions extending `RuntimeException`
93- Avoid broad `catch (Exception e)` unless at top-level handlers
94- Include context in exception messages
95 
96```java
97public class OrderNotFoundException extends RuntimeException {
98    public OrderNotFoundException(Long id) {
99        super("Order not found: id=" + id);
100    }
101}
102```
103 
104## Streams
105 
106- Use streams for transformations; keep pipelines short (3-4 operations max)
107- Prefer method references when readable: `.map(Order::getTotal)`
108- Avoid side effects in stream operations
109- For complex logic, prefer a loop over a convoluted stream pipeline
110 
111## References
112 
113See skill: `java-coding-standards` for full coding standards with examples.
114See skill: `jpa-patterns` for JPA/Hibernate entity design patterns.
115