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.