java-conventions

Java Conventions (stack-agnostic, Java 17+)

This skill encodes idioms that reduce bugs and improve readability in any Java codebase. Apply alongside the active framework plugin's conventions skill (e.g., spring-boot-plugin:spring-conventions).

Detection

Project is Java 17+ when:

• pom.xml has <java.version>17</java.version> or <maven.compiler.source>17</maven.compiler.source> (or higher).
• build.gradle / build.gradle.kts has sourceCompatibility = JavaVersion.VERSION_17 (or higher).

Read the build file first to learn the target Java version.

Records — prefer for value objects

Use records for immutable data carriers. They auto-generate constructor, equals, hashCode, toString.

// Prefer
public record Money(BigDecimal amount, Currency currency) {
    public Money {
        Objects.requireNonNull(amount, "amount");
        Objects.requireNonNull(currency, "currency");
        if (amount.compareTo(BigDecimal.ZERO) < 0) {
            throw new IllegalArgumentException("amount must be non-negative");
        }
    }

    public Money add(Money other) {
        if (!this.currency.equals(other.currency)) {
            throw new IllegalArgumentException("Currency mismatch");
        }
        return new Money(this.amount.add(other.amount), this.currency);
    }
}

// Avoid — a plain class with no behaviour
public class Money {
    private final BigDecimal amount;
    private final Currency currency;
    // ... boilerplate constructor, getters, equals, hashCode, toString
}

Compact constructor (without parameter list) is for validation only — do not assign fields there (the canonical constructor does that).

Sealed types — model closed hierarchies

public sealed interface Shape permits Circle, Rectangle, Triangle {}

public record Circle(double radius) implements Shape {}
public record Rectangle(double width, double height) implements Shape {}
public record Triangle(double base, double height) implements Shape {}

double area(Shape shape) {
    return switch (shape) {
        case Circle c    -> Math.PI * c.radius() * c.radius();
        case Rectangle r -> r.width() * r.height();
        case Triangle t  -> 0.5 * t.base() * t.height();
    };
}