java-coding-guideline

Documento original do Skill

Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.

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

java

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

❌ Don't

java

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

java

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

java

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

java

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

java

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

java

public final class SomeClass {

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

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

❌ Don't

java

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

java

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

java

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

java

final Integer someVariable = null;

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

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

❌ Don't

java

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

java

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

java

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

java

package com.example.project.initscript;

❌ Don't

java

package com.example.project.initScript;

Static Factory Methods

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

✅ Do

java

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

java

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

java

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

java

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

java

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

public final class SomeClass {

    private final SomeFeature feature;

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

❌ Don't

java

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

java

public final class SomeClass {
    // ...
}

❌ Don't

java

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

java

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.

java

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

Apply the Rule Per Condition

The same method may contain both assertions and exceptions.

java

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

java

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

❌ Don't

java

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

Implementing AutoCloseable

When implementing AutoCloseable:

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

✅ Do

java

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

java

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

java

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):

java

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

java

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:

java

// 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

java

if (someCondition) doSomething();

❌ Don't

java

if (someCondition) {
    doSomething();
}

Comments

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