Skip to content

Java 25 Engineering Standard

Version: 1.0.0

Status: official

Author: Enterprise AI Standards

Description

Official engineering standard for all Java projects developed within the organization.

Objective

Define mandatory engineering standards for Java 25 projects to ensure consistency, maintainability, scalability, performance and security.

Philosophy

Java projects must prioritize readability over cleverness, immutability over mutability, composition over inheritance and simplicity over unnecessary abstraction.

Principles

  • Keep code simple.
  • Prefer immutable objects.
  • Favor composition over inheritance.
  • Small focused classes.
  • Small focused methods.
  • Constructor Injection only.
  • Never optimize prematurely.
  • Measure before optimizing.
  • Prefer readability.
  • Every class has a single responsibility.

Project Structure

  • Maven Wrapper required.
  • Java 25 mandatory.
  • UTF-8 encoding.
  • Spring Boot 3.5+
  • Layered or Hexagonal Architecture.
  • Packages grouped by feature.

Language Features

  • Records preferred over DTO classes.
  • Pattern Matching enabled.
  • Enhanced switch expressions.
  • Text Blocks.
  • Local Variable Type Inference (var).
  • Sealed Classes when inheritance is restricted.
  • Use Optional as return value only.

Virtual Threads

Enabled: True

Rules

  • Every IO intensive application must use Virtual Threads.
  • Executors.newVirtualThreadPerTaskExecutor preferred.
  • Never pool virtual threads.
  • Avoid ThreadLocal.

Structured Concurrency

Enabled: True

Rules

  • Prefer StructuredTaskScope.
  • Cancel sibling tasks on failure.
  • Keep scopes small.

Records

  • DTOs should be Records.
  • Immutable by default.
  • No setters.

Sealed Classes

  • Use only when domain hierarchy is closed.

Pattern Matching

  • Prefer switch pattern matching.
  • Avoid instanceof chains.

Collections

  • Prefer List.of()
  • Prefer Map.of()
  • Immutable collections by default.

Streams

  • Prefer Streams for transformations.
  • Avoid nested streams.
  • Never abuse parallelStream().

Optional

  • Never use Optional in entity fields.
  • Never use Optional parameters.
  • Return Optional only.

Exceptions

  • Custom Exceptions extend RuntimeException.
  • Never swallow exceptions.
  • Never catch Exception.

Logging

  • SLF4J only.
  • Parameterized logging.
  • Never System.out.println()

Performance

  • Measure before optimization.
  • Prefer Virtual Threads.
  • Avoid unnecessary synchronization.

Security

  • Validate every external input.
  • Never expose stack traces.
  • Secrets outside repository.

Testing

  • JUnit 5.
  • AssertJ.
  • Testcontainers.
  • Mockito.

Observability

  • Micrometer.
  • OpenTelemetry.
  • Health Checks.

Documentation

  • README mandatory.
  • JavaDoc only for public APIs.

Best Practices

  • Constructor Injection.
  • Final variables.
  • Small classes.
  • Small methods.
  • Immutable Objects.

Anti Patterns

  • God Classes.
  • Static Mutable State.
  • ThreadLocal.
  • Long Methods.
  • Boolean Parameters.
  • Field Injection.
  • Null Returns.
  • Primitive Obsession.

Review Checklist

  • [ ] Java 25
  • [ ] Virtual Threads
  • [ ] Unit Tests
  • [ ] Integration Tests
  • [ ] README Updated
  • [ ] Docker Ready
  • [ ] Sonar Clean

Examples

Records

public record UserDto(Long id, String name) {}

Virtual Threads

try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
    ...
}

Constructor Injection

@Service
public class UserService {
    private final UserRepository repository;

    public UserService(UserRepository repository) {
        this.repository = repository;
    }
}

References

  • https://docs.oracle.com/en/java/
  • https://openjdk.org/
  • https://inside.java/