Java Coding Guideline

CRITICAL: These rules apply to ALL Java code unless explicitly overridden by more specific skills.

Import Statements

Always use explicit imports without wildcards for better code clarity and maintainability.

✅ Do

import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.fail;

❌ Don't

import static org.assertj.core.api.Assertions.*;

---

Vertical Spacing (Readability)

Use consistent vertical spacing inside classes to make diffs smaller and code easier to scan.

Rule

• Insert exactly one blank line between:
  • field blocks and the next field block (when grouped)
  • fields and the first constructor
  • constructors and methods
  • methods and the next method
• Also insert one blank line right after the opening { of a class (before the first field/initializer), unless the class is intentionally empty.

✅ Do

public final class SomeClass {

    @NonNull
    private final String fieldA;

    @NonNull
    private final String fieldB;

    public void someFunc() {
        // some action
    }

    public String getFieldA() {
        return fieldA;
    }
}

❌ Don't

public final class SomeClass {
    @NonNull
    private final String fieldA;
    @NonNull
    private final String fieldB;
    public void someFunc() {
        // some action
    }
    public String getFieldA() {
        return fieldA;
    }
}

Constructors

Use a single primary constructor and delegate auxiliary constructors using this().

✅ Do

public final class SomeClass {

    private final int field1;
    private final int field2;

    public SomeClass() {
        this(1, 2);
    }

    public SomeClass(int field1, int field2) {
         this.field1 = field1;
         this.field2 = field2;
    }
}

❌ Don't

public final class SomeClass {

    private final int field1;
    private final int field2;

    public SomeClass() {
        this.field1 = 1;
        this.field2 = 2;
    }

    public SomeClass(int field1, int field2) {
         this.field1 = field1;
         this.field2 = field2;
    }
}

---

Optional Usage

Avoid using Optional as return values or parameters. Use @Nullable annotations instead.

✅ Do

public final class SomeClass {

    @Nullable
    public Integer someNullable() {
        if (something) return null;
        return 1;
    }

    public void func(@Nullable Integer param) {
        // do something
    }
}

❌ Don't

public final class SomeClass {

    @NonNull
    public Optional<Integer> someNullable() {
        if (something) return Optional.ofNullable(null);
        return Optional.ofNullable(1);
    }

    public void func(@NonNull Optional<Integer> param) {
        // do something
    }
}

---

Wrapper vs Primitive Types

• Use wrapper types when null is expected
• Use primitive types when null should not occur

✅ Do

public final class SomeClass {

    private final int field1;

    @Nullable
    private final Long field2;

    public SomeClass(int field1, @Nullable Long field2) {
        this.field1 = field1;
        this.field2 = field2;
    }
}

❌ Don't

public final class SomeClass {

    @NonNull
    private final Integer field1;

    @Nullable
    private final Long field2;

    public SomeClass(@NonNull Integer field1, @Nullable Long field2) {
        this.field1 = field1;
        this.field2 = field2;
    }
}

---

Null Comparison

• Use A == null for general cases
• Use Objects.isNull for Stream API or functional programming contexts

✅ Do

final Integer someVariable = null;

if (someVariable == null) {
    // do something
}

List<Integer> lists = new ArrayList<>();
lists.stream()
  .filter(Objects::isNull)
  .collect(Collectors.toList());

❌ Don't

final Integer someVariable = null;

if (Objects.isNull(someVariable)) {
    // do something
}

List<Integer> lists = new ArrayList<>();
lists.stream()
  .filter(p -> p == null)
  .collect(Collectors.toList());

---

Nullability Annotations

• Use JSpecify annotations
• Apply @Nullable and @NonNull to all methods including private ones
• Avoid class-level or package-level annotations (Lombok compatibility issues)

✅ Do

public final class SomeClass {

    @Nullable
    private final Integer field1;

    @NonNull
    private final String field2;

    @NonNull
    public String func() {
        return process();
    }

    @Nullable
    private String process() {
        if (field1 == null) return null;
        return "awesome";
    }
}

❌ Don't

public final class SomeClass {

    private final Integer field1;
    private final String field2;

    public String func() {
        return process();
    }

    private String process() {
        if (field1 == null) return null;
        return "awesome";
    }
}

---

Package Naming

Use all lowercase and numbers only, following Google Java Style Guide conventions.

✅ Do

package com.example.project.initscript;

❌ Don't

package com.example.project.initScript;

---

Static Factory Methods

Use only of naming convention. For multiple types, use format of<Postfix>.

✅ Do

public final class SomeClass {

    private final int field1;

    private SomeClass(int field1) {
        this.field1 = field1;
    }

    public static SomeClass ofDefault() {
        return new SomeClass(1);
    }

    public static SomeClass ofSpecial() {
        return new SomeClass(2);
    }
}

❌ Don't

public final class SomeClass {

    private final int field1;

    private SomeClass(int field1) {
        this.field1 = field1;
    }

    public static SomeClass from() {
        return new SomeClass(1);
    }

    public static SomeClass valueOf() {
        return new SomeClass(2);
    }
}

Resource Management

Always use try-with-resources for AutoCloseable resources. Never rely on finalizers.

Try-With-Resources

✅ Do

public String readFile(@NonNull Path path) throws IOException {
    try (var reader = Files.newBufferedReader(path)) {
        return reader.lines().collect(Collectors.joining("\n"));
    }
}

// Multiple resources
public void copyStream(@NonNull InputStream in, @NonNull OutputStream out) throws IOException {
    try (in; out) {  // Java 9+: can use already-declared variables
        in.transferTo(out);
    }
}

❌ Don't

public String readFile(@NonNull Path path) throws IOException {
    BufferedReader reader = Files.newBufferedReader(path);
    try {
        return reader.lines().collect(Collectors.joining("\n"));
    } finally {
        reader.close();  // The original exception may be suppressed if one occurs here
    }
}

---

Composition over Inheritance

Prefer composition over inheritance.

✅ Do

public final class SomeFeature {
    public void func() { /* ... */ }
}

public final class SomeClass {

    private final SomeFeature feature;

    public void func2() {
        feature.func();
        // do something
    }
}

❌ Don't

public class SomeFeature {
    public void func() { /* ... */ }
}

public final class SomeClass extends SomeFeature {

    public void func2() {
        super.func();
        // do something
    }
}

---

Immutable Objects

All objects should use final keyword unless needed for extension or framework requirements.

✅ Do

public final class SomeClass {
    // ...
}

❌ Don't

public class SomeClass {
    // ...
}

---

Assertions and Exceptions

Choose between an assertion and an exception based on the trust boundary and the caller's recovery responsibility. Apply this rule to each condition, not to an entire class or method.

Do not infer the boundary from a Java access modifier or a component name. A public method may be an internal API, while a private parser may process external input.

Decision Table

| Condition | Mechanism | |-----------|-----------| | Invalid external request, command, message, or public API argument | Throw an exception | | Invalid runtime configuration | Throw an exception | | Network, database, filesystem, or external service failure | Throw an exception | | Security, authorization, or data integrity check | Throw an exception | | Caller must translate, retry, trace, log, or otherwise handle the failure | Throw an exception | | Programmer-controlled precondition or postcondition in an internal API | Use assert | | Relationship guaranteed by internal wiring or dispatch | Use assert | | State that is unreachable when the implementation is correct | Use assert |

Throw Exceptions Across External Boundaries

Throw an exception when a failure can occur during valid runtime operation or the caller must be able to respond to it. External boundaries include:

• HTTP, RPC, XML-RPC, CLI, message, and event handlers
• Public library APIs called by independently developed consumers
• User-supplied or tenant-supplied input
• Runtime configuration
• Unexpected or invalid data from a network, database, filesystem, or external service that can occur during normal operation

Use an exception even when assertions are enabled. Externally visible behavior must not depend on the JVM -ea option.

Choose an exception type that communicates the failure:

• Use IllegalArgumentException for an invalid caller-supplied argument
• Use IllegalStateException when the current runtime state cannot satisfy the operation
• Use a domain-specific exception for operational failures that callers must distinguish
• Use UncheckedIOException when intentionally exposing an I/O failure as an unchecked exception

Document externally visible exceptions with @throws.

Assert Internal Invariants

Use assert for programmer-controlled preconditions, postconditions, and invariants in internal APIs. This includes internal publishers, generators, converters, and parsers that consume trusted application data.

Typical assertion cases include:

• An internal resolver must produce a nonblank key
• A generator or converter must produce a nonempty result
• Related domain objects must reference each other
• A persistence operation must populate an ID
• A query immediately following an insert must return the inserted entity
• An interceptor must have populated an internal context value
• A branch must be unreachable when internal dispatch is correct

public void publish(@NonNull String objectKey, @NonNull String generatedScript) {
    assert !objectKey.isBlank();
    assert !generatedScript.isBlank();

    objectStore.put(objectKey, generatedScript);
}

Assertions may be disabled in production. Therefore:

• Never use assertions for external input validation
• Never use assertions for authorization or security checks
• Never use assertions for conditions that require runtime recovery
• Never place side effects inside an assertion expression
• Never catch AssertionError as normal control flow
• Keep code correct and secure when assertions are disabled

Add an assertion message when the invariant is not obvious.

assert collector.getAgentId() == agent.getId() : "collector must own the agent";

Apply the Rule Per Condition

The same method may contain both assertions and exceptions.

public void resize(@NonNull Pool pool, @NonNull Bucket bucket, long requestedSize, long minimumSize) {
    assert pool.getId() == bucket.getPoolId();
    assert pool.getType() == PoolType.OBJECT_STORAGE;

    if (requestedSize < minimumSize) {
        throw new IllegalArgumentException("requested size is smaller than the minimum size");
    }
}

The pool relationship is an internal routing invariant. The requested size is a runtime argument that a caller may legitimately provide incorrectly.

An internal API must still throw exceptions for operational failures such as an S3 upload failure, database error, or network timeout. Internal API status alone does not turn an expected runtime failure into an assertion.

Validate Once, Then Assert Internally

Validate external data at the boundary with an exception. After converting it into trusted internal data, use assertions to document the propagated invariant.

A parser follows the same rule:

• Throw a parse exception when parsing external or untrusted content
• Assert assumptions when parsing content produced and validated by the same application

Exception Logging

Throwing an exception does not mean that every layer should log it. Preserve the original cause and propagate the exception until a layer can handle, translate, retry, or terminate the operation. Log the exception once at that handling boundary instead of logging and rethrowing it at every layer.

---

Exception Catching

Catch only the minimum necessary exceptions.

✅ Do

try {
    // do something
} catch (IllegalArgumentException e) {
    // do catch
}

❌ Don't

try {
    // do something
} catch (RuntimeException e) {
    // do catch
}

Implementing AutoCloseable

When implementing AutoCloseable:

1. Make close() idempotent (safe to call multiple times)
2. Never throw exceptions from close() (suppressed exceptions problem)
3. Log errors instead of throwing them

✅ Do

public final class DatabaseConnection implements AutoCloseable {

    @NonNull
    private final Connection connection;

    private volatile boolean closed = false;

    @Override
    public void close() {
        if (closed) return;  // Idempotent: safe to call multiple times

        closed = true;
        try {
            connection.close();
        } catch (SQLException e) {
            // Log only; do not throw (exceptions in close can suppress the original)
            logger.warn("Failed to close connection", e);
        }
    }
}

❌ Don't

public final class DatabaseConnection implements AutoCloseable {

    @NonNull
    private final Connection connection;

    @Override
    public void close() throws SQLException {
        connection.close();  // Not idempotent; exception propagates
    }
}

---

Date/Time API

Use java.time (JSR-310) exclusively. java.util.Date and java.util.Calendar are banned in new code.

Type Selection

| Use Case | Type | Example | |----------|------|---------| | Storage/transfer (UTC) | Instant | API timestamps, DB storage | | User display | ZonedDateTime | Time shown in UI | | Date only | LocalDate | Birthdays, expiration dates | | Time only | LocalTime | Business hours, alarms | | Duration | Duration / Period | Elapsed time, date differences |

✅ Do

public final class Event {

    @NonNull
    private final Instant createdAt;  // UTC timestamp

    @NonNull
    private final LocalDate eventDate;  // Date only

    @NonNull
    private final ZoneId timeZone;  // Display time zone

    @NonNull
    public ZonedDateTime displayTime() {
        return createdAt.atZone(timeZone);
    }
}

Formatter reuse (thread-safe):

public final class DateFormats {

    // DateTimeFormatter is thread-safe, so reuse as constants
    public static final DateTimeFormatter ISO_DATE = DateTimeFormatter.ISO_LOCAL_DATE;

    public static final DateTimeFormatter ENGLISH_DATE = DateTimeFormatter.ofPattern("MMM dd, yyyy");

    private DateFormats() {}
}

❌ Don't

public final class Event {

    @NonNull
    private final Date createdAt;  // Do not use java.util.Date

    @NonNull
    private final Calendar calendar;  // Do not use java.util.Calendar

    @NonNull
    public String format() {
        SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd");  // Not thread-safe
        return sdf.format(createdAt);
    }
}

Legacy Interop (boundary only)

When interfacing with legacy APIs that require Date, convert at the boundary:

// Instant → Date (boundary layer only)
Date legacyDate = Date.from(instant);

// Date → Instant (convert immediately on receipt)
Instant instant = legacyDate.toInstant();

---

Additional Guidelines

Builder Pattern

Use Lombok-style builders for API consistency.

Variable and Method Naming

• Use var keyword from JVM 10+
• Use meaningful variable names
  • But avoid too long variable, function, field names
• Method names should be verbs
• Avoid using 'get' prefix except for getters

Camel Case Convention

Apply camel case to mixed-case words and abbreviations (e.g., "MultiNIC" becomes "MultiNic").

Control Flow Statements

Use one-liner syntax for simple if statements without braces.

✅ Do

if (someCondition) doSomething();

❌ Don't

if (someCondition) {
    doSomething();
}

Comments

• Use comments only in special cases
• TODO comments should be for immediate tasks
• Avoid unnecessary comments that restate the code

---

See Also

Reference Guides

For deeper understanding of specific topics:

• references/async.md - CompletableFuture and async programming patterns
• references/javadoc.md - Javadoc conventions and exception documentation
• references/lombok.md - Allowed and banned Lombok annotations
• references/security-resources.md - Security best practices, password handling, SQL injection prevention, PII masking