jungho-git/java

Java

• Shared examples and formatting reference: references/EXAMPLE.md.
• Keep new guidance, snippets, and edits aligned with that file.

---

Scope

Use this rule when:

• editing Java services, controllers, repositories, DTOs, mappers, or utilities
• changing method signatures, DTO fields, mapper parameters, or returned shapes
• tracing caller impact across Java layers
• aligning Java mapper interfaces with MyBatis XML

Java changes should preserve explicit contracts and local code shape.

---

Baseline

• Use Java 11 only.
• Do not use records, sealed classes, pattern matching for instanceof, text blocks, switch expressions, or post-Java 11 features.
• Never use var; declare explicit local types.
• When generating new code, keep newly authored local variable and constant names at 30 chars or fewer by default; preserve Java contracts through local aliases.
• Never add @SuppressWarnings; fix the cause or report the remaining warning.
• Do not add final to fields or local variables as a default habit.

---

Contract Rules

• Treat method signatures, DTO fields, mapper parameters, and result shapes as contract surfaces.
• Check callers before changing signatures or DTO fields.
• Use Objects.requireNonNull() for required parameters at boundaries.
• Guard against null at system boundaries: user input, external API responses, DB results, and deserialization.
• Avoid blanket internal null checks when nearby code already guarantees the contract.
• Never use String.valueOf(obj) for nullable values; use Objects.toString(obj, "") when an empty fallback is intended.
• Return defensive copies of mutable state.

---

Layering

• Keep business logic and utility processing in Java.
• Keep SQL/XML focused on retrieval and persistence.
• Do not move format conversion, string manipulation, conditional branching, calculations, or code mapping into queries.
• Allow SQL functions only for simple display-level transformations, not business rules.

---

Method Shape

• Prefer explicit readable branches over clever compression.
• Keep related statements together as one cohesive chunk.
• Preserve existing cohesive methods when editing or generating Java code.
• Do not split an existing readable method into tiny private methods just to reduce length or appear cleaner.
• Do not introduce speculative helpers, wrappers, or utility classes.
• Create private methods only for real duplication, unavoidable complexity, a true boundary, or a contract/test seam.
• A readable forty-line method is better than multiple tiny helpers connected only by call chains.

---

Exceptions And Resources

• Use try-with-resources for AutoCloseable resources.
• Catch specific exceptions; do not catch broad Exception or Throwable unless an existing framework boundary requires it.
• Never leave catch blocks empty; log or rethrow with context.

---

Collections And Strings

• Declare collections by interface such as List<T>, not concrete implementations unless required.
• Use StringBuilder inside loops.
• Use String.format() only for complex formatting; avoid noisy concatenation.

---

Formatting

• Follow Google Java Style where it does not conflict with higher-priority local rules.
• Use Stroustrup clause layout: else, catch, and finally start on the next line after the closing brace.
• Always use braces for if, else, for, while, and do-while bodies.
• Prefer early returns to keep the happy path flat.
• Use exactly one space around binary operators.
• Never vertically align declarations, assignments, annotations, or operators.

---

Validation Focus

• changed method contracts and callers
• DTO field shape and nullability
• mapper interface and XML alignment
• controller/service caller impact
• no new @SuppressWarnings

Do not run Gradle compile or test commands unless the user explicitly allows it.