java-conventions

Java Conventions

Package Naming

com.{org}.{domain}.{layer}

Class Naming Suffixes

Method Ordering in Classes

1. Static fields (logger, constants)
2. Instance fields (final dependencies)
3. Constructor
4. Public API methods (business operations)
5. Package-private / protected methods
6. Private helper methods
7. Static factory/utility methods

Null Handling

• Return Optional<T> for methods that might not return a value — NEVER return null from public methods
• Use @NonNull / @Nullable annotations at entry points
• NEVER return null for collections — return empty collections

// GOOD
public Optional<Order> findById(UUID id) {
    return orderRepository.findById(id);
}

Immutability

• Prefer final fields wherever possible
• Use Java Records for DTOs (Java 16+)
• Use Collections.unmodifiableList() for collection fields

public record CreateOrderRequest(
    @NotNull String customerId,
    @NotEmpty List<OrderItemRequest> items
) {}

Import Ordering

1. java.*
2. javax.*
3. org.*
4. com.*
5. Static imports last

No wildcard imports — always import specific classes.