Java Rules

Java Rules

These rules come from app/rules/java/ in ai-toolkit. They cover the project's standards for coding style, frameworks, patterns, security, and testing in Java. Apply them when writing or reviewing Java code.

Java Coding Style

Naming

• PascalCase: classes, interfaces, enums, records, annotations.
• camelCase: methods, variables, parameters.
• UPPER_SNAKE: constants (static final).
• Package names: lowercase, dot-separated, reverse domain (com.company.project).
• No Hungarian notation. No I prefix on interfaces.

Modern Java (17+)

• Use record for immutable data carriers. No need for Lombok in most cases.
• Use sealed classes/interfaces for restricted hierarchies.
• Use pattern matching: if (obj instanceof String s) instead of cast.
• Use switch expressions with arrow syntax and exhaustiveness.
• Use text blocks (""") for multiline strings (SQL, JSON, HTML).

Types

• Use var for local variables when the type is obvious from the right-hand side.
• Use Optional<T> for return types that may be absent. Never for fields or params.
• Prefer List.of(), Map.of(), Set.of() for immutable collections.
• Use Stream for collection transformations. Avoid streams for simple iterations.

Classes

• Prefer composition over inheritance. Use interfaces for abstraction.
• Keep classes focused: single responsibility.
• Use final on classes not designed for extension.
• Use private constructors + static factory methods for controlled instantiation.
• Records over POJOs for value types. Lombok only if records are insufficient.

Methods

• Max 20-30 lines per method. Extract when longer.
• Use @Override on every overridden method.
• Return empty collections over null. Use Collections.emptyList() or List.of().
• Avoid checked exceptions for programming errors. Use runtime exceptions.

Formatting

• Use project formatter (Google Java Format or IDE-configured).
• Use @SuppressWarnings sparingly and with specific warning names.
• Use final for parameters and local variables where practical.

Nullability

• Annotate with @Nullable / @NonNull from JSpecify or JetBrains.
• Use Objects.requireNonNull() at public API boundaries.
• Never return null from collections or arrays. Return empty.
• Use Optional for genuinely optional return values.

Documentation

• Javadoc on all public classes and methods.
• Use @param, @return, @throws tags for public API methods.
• Skip Javadoc for obvious getters, toString(), and equals().

Java Frameworks

Spring Boot

• Use Spring Boot 3+ with Java 17+ minimum.
• Use @RestController for REST APIs. Return ResponseEntity for status control.
• Use @Valid + Jakarta Bean Validation for request validation.
• Use profiles (@Profile) for environment-specific configuration.
• Use application.yml over application.properties for readability.
• Externalize config: env vars > config files > hardcoded defaults.

Spring Data JPA

• Use repository interfaces extending JpaRepository.
• Use @Query with JPQL for custom queries. Use native queries only when needed.
• Use @EntityGraph to prevent N+1 queries in associations.
• Use Specification for dynamic query building.
• Always use @Transactional at the service layer, not repository.

Spring Security

• Use SecurityFilterChain bean configuration (not WebSecurityConfigurerAdapter).
• Use @PreAuthorize / @Secured for method-level authorization.
• Use BCrypt for password encoding: new BCryptPasswordEncoder().
• Configure CORS, CSRF, and session management explicitly.
• Use OAuth2 Resource Server for JWT validation in APIs.

Hibernate / JPA

• Use FetchType.LAZY by default on all associations.
• Use @BatchSize or @Fetch(FetchMode.SUBSELECT) to avoid N+1.
• Use @Version for optimistic locking on entities.
• Use DTOs (records) for read queries. Do not expose entities in APIs.
• Use Flyway or Liquibase for schema migrations.

Quarkus / Micronaut

• Use for microservices and serverless where startup time matters.
• Use compile-time DI (Micronaut) or build-time optimization (Quarkus).
• Use reactive patterns with Mutiny (Quarkus) or Reactor (Micronaut).
• Use native image builds with GraalVM for production deployments.

Build Tools

• Use Gradle (Kotlin DSL) for new projects. Maven for enterprise legacy.
• Use dependency management to unify versions across modules.
• Use Bill of Materials (BOM) imports for consistent Spring versions.
• Use Spotless or Checkstyle for enforced code formatting.

Logging

• Use SLF4J facade with Logback or Log4j2 backend.
• Use structured logging with MDC for correlation IDs.
• Use parameterized logging: log.info("User {} created", userId).
• Never log sensitive data (passwords, tokens, PII).

Java Patterns

Error Handling

• Use unchecked exceptions for programming errors (IllegalArgumentException).
• Use checked exceptions only for recoverable conditions the caller must handle.
• Create domain exception hierarchy: AppException -> NotFoundException, etc.
• Never catch Exception or Throwable broadly. Catch specific types.
• Use try-with-resources for all AutoCloseable resources.

Immutability

• Use record for immutable value objects (Java 16+).
• Use List.copyOf(), Map.copyOf() to create unmodifiable copies.
• Make fields private final. No setters unless mutation is required.
• Return defensive copies of mutable collections from getters.
• Use builder pattern for constructing immutable objects with many fields.

Optional

• Use Optional<T> as return type for methods that may not return a value.
• Chain: optional.map(...).orElseThrow(...). Avoid isPresent() + get().
• Never use Optional for fields, method parameters, or collection elements.
• Use Optional.empty() over null. Use Optional.ofNullable() at boundaries.

Streams

• Use streams for transformations: filter, map, collect.
• Avoid side effects in stream operations. Keep them pure.
• Use Collectors.toUnmodifiableList() for immutable results.
• Prefer for loop for simple iterations that do not transform data.
• Use Stream.of() or IntStream.range() for generating sequences.

Dependency Injection

• Use constructor injection exclusively. No field or setter injection.
• Accept interfaces in constructors, not implementations.
• Use @Component, @Service, @Repository for Spring-managed beans.
• Keep the number of constructor dependencies under 5. Split if more.

Concurrency

• Use ExecutorService and CompletableFuture for async operations.
• Use virtual threads (Java 21+) for I/O-bound concurrent work.
• Use ConcurrentHashMap, AtomicInteger for thread-safe operations.
• Avoid synchronized blocks when possible -- use higher-level concurrency.
• Use ReentrantReadWriteLock for read-heavy shared state.

Design Patterns

• Use Strategy pattern (via interfaces) over switch/if-else chains.
• Use Factory methods for flexible object creation.
• Use Decorator pattern for composable behavior augmentation.
• Avoid Singleton pattern -- use DI container for lifecycle management.