modern-java-21

Apply a single authoritative rule set to every touched .java file covering imports, nullability, immutability, and size limits, and back it with build quality gates like Checkstyle MethodLength and FileLength so violations fail the build rather than relying on review alone.

This standard uses seven groups in order: static imports, java.*, jakarta.*, javax.*, com.*, org.*, then everything else such as io.* or reactor.*. Each group is sorted lexicographically with exactly one blank line between non-empty groups, and wildcard imports are banned.

This project standard prohibits var in all project-controlled source, including tests and generated templates, requiring explicit declared types for readability. Java still resolves types statically, but the convention keeps the type visible to readers.

Every main-source package carries @NullMarked in package-info.java so unannotated types are non-null, and @Nullable marks exceptions. The same org.jspecify.annotations vocabulary works on both Spring Boot 3 and 4, replacing Spring's own @Nullable and JSR-305.

Use Optional only as a return type for a legitimately absent value. For fields, record components, entity attributes, and parameters, use JSpecify @Nullable instead, since it costs no allocation, survives serialization, and maps correctly in JPA.

Methods up to 40 lines need no justification, 41-60 require scrutiny, and 61-100 need a documented reason. A method over 100 lines or a class over 1000 lines must be refactored without exception because the build gates fail at exactly those numbers.