standards-java

Java Coding Standards

Core Principles

1. Simplicity: Simple, understandable code
2. Readability: Readability over cleverness
3. Maintainability: Code that's easy to maintain
4. Testability: Code that's easy to test
5. SOLID: Follow SOLID principles for object-oriented design
6. DRY: Don't Repeat Yourself - but don't overdo it

General Rules

• Early Returns: Use early returns to avoid nesting
• Descriptive Names: Meaningful names for classes, methods, and variables
• Minimal Changes: Only change relevant code parts
• No Over-Engineering: No unnecessary complexity
• Immutability: Prefer immutable objects where possible
• Minimal Comments: Code should be self-explanatory. No redundant comments!

Naming Conventions

| Element | Convention | Example | |---------|------------|---------| | Classes | PascalCase | UserService, OrderRepository | | Interfaces | PascalCase | UserRepository, PaymentProcessor | | Methods | camelCase | getUserById, calculateTotal | | Variables | camelCase | firstName, totalAmount | | Constants | UPPER_SNAKE_CASE | MAX_RETRY_COUNT, DEFAULT_TIMEOUT | | Packages | lowercase.dot.separated | com.example.service, com.example.repository | | Test Classes | ClassNameTest | UserServiceTest, OrderRepositoryTest | | Test Methods | descriptive_snake_case or camelCase | shouldReturnUserWhenIdExists |

Project Structure

Maven Project

myproject/
├── pom.xml
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/example/myapp/
│   │   │       ├── Application.java        # Main entry point
│   │   │       ├── config/
│   │   │       │   └── AppConfig.java      # Configuration
│   │   │       ├── domain/
│   │   │       │   └── User.java           # Domain models
│   │   │       ├── repository/
│   │   │       │   └── UserRepository.java # Data access
│   │   │       ├── service/
│   │   │       │   └── UserService.java    # Business logic
│   │   │       └── controller/
│   │   │           └── UserController.java # REST endpoints
│   │   └── resources/
│   │       ├── application.properties
│   │       └── application-dev.properties
│   └── test/
│       ├── java/
│       │   └── com/example/myapp/
│       │       ├── service/
│       │       │   └── UserServiceTest.java
│       │       └── repository/
│       │           └── UserRepositoryTest.java
│       └── resources/
│           └── application-test.properties
└── README.md

Gradle Project

myproject/
├── build.gradle or build.gradle.kts
├── settings.gradle or settings.gradle.kts
├── src/
│   ├── main/
│   │   └── java/...      # Same structure as Maven
│   └── test/
│       └── java/...      # Same structure as Maven
└── README.md

Modern Java Features

Recommended: Use the latest LTS for new projects (currently Java 21 or Java 25).

Java 17 Features

Records (Immutable Data)

// Replace verbose POJOs with records
public record User(String id, String name, String email) {
    // Compact constructor for validation
    public User {
        if (name == null || name.isBlank()) {
            throw new IllegalArgumentException("Name cannot be blank");
        }
    }

    // Custom methods allowed
    public String displayName() {
        return name.toUpperCase();
    }
}

// Usage
var user = new User("1", "John Doe", "john@example.com");
System.out.println(user.name()); // Auto-generated accessor

Sealed Classes (Restricted Hierarchies)

// Define closed set of subclasses
public sealed interface Result<T>
    permits Success, Failure {
}

public record Success<T>(T value) implements Result<T> {}
public record Failure<T>(String error) implements Result<T> {}

// Pattern matching exhaustiveness
public <T> void handleResult(Result<T> result) {
    switch (result) {
        case Success<T> s -> System.out.println("Success: " + s.value());
        case Failure<T> f -> System.out.println("Error: " + f.error());
        // No default needed - compiler knows all cases
    }
}

Pattern Matching (instanceof)

// Old way
if (obj instanceof String) {
    String s = (String) obj;
    System.out.println(s.toUpperCase());
}

// Modern way - pattern matching
if (obj instanceof String s) {
    System.out.println(s.toUpperCase());
}

// Pattern matching in switch
public String formatValue(Object obj) {
    return switch (obj) {
        case Integer i -> "Number: " + i;
        case String s -> "Text: " + s;
        case null -> "null";
        default -> "Unknown: " + obj;
    };
}

Text Blocks (Multi-line Strings)

// Old way
String json = "{\n" +
              "  \"name\": \"John\",\n" +
              "  \"age\": 30\n" +
              "}";

// Modern way - text block
String json = """
    {
      "name": "John",
      "age": 30
    }
    """;

Switch Expressions

// Old switch statement
String result;
switch (day) {
    case MONDAY:
    case FRIDAY:
        result = "Work";
        break;
    case SATURDAY:
    case SUNDAY:
        result = "Weekend";
        break;
    default:
        result = "Unknown";
}

// Modern switch expression
String result = switch (day) {
    case MONDAY, FRIDAY -> "Work";
    case SATURDAY, SUNDAY -> "Weekend";
    default -> "Unknown";
};

Java 21 Features

Virtual Threads

// Traditional platform threads - expensive, limited scalability
try (var executor = Executors.newFixedThreadPool(100)) {
    for (int i = 0; i < 10000; i++) {
        executor.submit(() -> fetchData());
    }
}

// Virtual threads - lightweight, millions possible
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
    for (int i = 0; i < 10000; i++) {
        executor.submit(() -> fetchData());
    }
}

// Start virtual thread directly
Thread.startVirtualThread(() -> {
    // Task code
});

// Structured concurrency (preview in Java 21)
try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
    Future<String> user = scope.fork(() -> fetchUser(id));
    Future<List<Order>> orders = scope.fork(() -> fetchOrders(id));

    scope.join();           // Wait for all tasks
    scope.throwIfFailed();  // Throw if any failed

    return new UserDetails(user.resultNow(), orders.resultNow());
}

Sequenced Collections

// New interfaces: SequencedCollection, SequencedSet, SequencedMap

// Get first and last elements
List<String> list = List.of("a", "b", "c");
String first = list.getFirst();  // "a"
String last = list.getLast();    // "c"

// Reversed view (not a copy!)
List<String> reversed = list.reversed();

// Works with Set
LinkedHashSet<String> set = new LinkedHashSet<>(List.of("a", "b", "c"));
set.addFirst("z");  // z, a, b, c
set.addLast("x");   // z, a, b, c, x

// Works with Map
LinkedHashMap<String, Integer> map = new LinkedHashMap<>();
map.putFirst("first", 1);
map.putLast("last", 99);

Pattern Matching for switch (finalized)

// Pattern matching with null handling
String formatted = switch (obj) {
    case null -> "null";
    case Integer i -> "Number: " + i;
    case String s -> "Text: " + s;
    case List<?> list -> "List of " + list.size() + " items";
    default -> "Unknown";
};

// Guard patterns
String category = switch (value) {
    case Integer i when i < 0 -> "Negative";
    case Integer i when i == 0 -> "Zero";
    case Integer i -> "Positive";
    default -> "Not a number";
};

Record Patterns (finalized)

record Point(int x, int y) {}
record Circle(Point center, int radius) {}

// Deconstruct records in patterns
static void printPoint(Object obj) {
    if (obj instanceof Point(int x, int y)) {
        System.out.println("x: " + x + ", y: " + y);
    }
}

// Nested deconstruction
static void printCircle(Object obj) {
    if (obj instanceof Circle(Point(int x, int y), int r)) {
        System.out.println("Circle at (" + x + ", " + y + ") with radius " + r);
    }
}

// In switch
static String describ