java-conventions

Java Conventions

Used to unify coding habits and comment requirements in Java projects, helping you ensure consistency and maintainability without introducing over-engineering.

Usage process

• First determine the scope of changes: only modify the currently involved classes/methods, and do not perform unrelated formatting.
• First unify the basic standards: logging, null checks, utility class selection, and Bean annotation strategy.
• Then perform comment checks: object comments, method comments, and logic block comments (not simple CRUD).
• Finally verify: submit only after compilation + tests pass.

Coding standards

Logging standards (required)

• Use SLF4J consistently, combined with Lombok annotations (for example @Slf4j）。
• Prohibit System.out.println、printStackTrace()。
• Log content should avoid sensitive information and full output of large objects.

Example:

import lombok.extern.slf4j.Slf4j;

@Slf4j
public class UserService {
  public void handle(String userId) {
    log.info("handle userId={}", userId);
  }
}

Bean/Lombok annotations (choose by scenario)

• Domain/DTO/VO/BO, etc.: choose as needed @Getter/@Setter/@Builder/@Data。
• When controllable equals/hashCode/toString is needed: prefer explicitly selecting a combination of Lombok annotations, avoiding a one-size-fits-all approach.
• When objects are serialized/logged frequently: pay attention to toString sensitive fields and large fields.

Null checks and defensive programming

• For null checks, prefer JDK utilities:Objects.requireNonNull、Objects.nonNull、Optional。
• Do not use a "global try/catch that swallows exceptions" approach to hide null pointer problems; input should be validated at boundaries.

Example:

import java.util.Objects;

public void updateName(String name) {
  Objects.requireNonNull(name, "name must not be null");
}

Utility class priority (strings / collections, etc.)

• Priority: Spring → Apache Commons → Hutool → Guava.
• Provided existing dependencies satisfy the need, avoid introducing a new dependency for a small utility method.
• When similar utilities exist at the same time, unify the team's choice to avoid mixing them everywhere.

Design and splitting

• Complex logic: prefer design patterns (Strategy, Template Method, Chain of Responsibility, etc.) to improve extensibility and testability.
• Simple logic: avoid over-design and over-splitting, and prioritize readability.
• Domain modeling: converge business rules into domain objects/domain services as much as possible, and avoid piling anemic models in ServiceImpl.

Comment standards

Rules (required)

• When creating or updating any object/method, perform comment checks and complete/improve object comments and method comments.
• If the method logic is not the simplest CRUD, add comments by logic block to explain the key intent and boundary conditions.
• Controller, Service, ServiceImpl, and Mapper all require comments, and comments must remain consistent with the code (do not write outdated comments).

Suggested template

• Class: explain responsibility boundaries, inputs and outputs, and key constraints.
• Method: explain what it does, the meaning of key parameters, and exception/return conventions.

For a more complete comment template and checklist, see references/api_reference.md。

Output requirements (for delivery during Review/refactoring)

• List: the standard points that have been adjusted (logging/null checks/utility classes/comments).
• Include: the list of affected files and the verification method (compilation/tests).

Common pitfalls (Gotchas)

1. Version compatibility: Note the compatibility between framework versions and dependency libraries; APIs may differ across versions
2. Configuration file format: Configuration file format errors are the most common problem; it is recommended to use the editor's syntax checking
3. Environment variables: Ensure all necessary environment variables are set correctly, and do not hard-code sensitive information
4. Dependency conflicts: Pay attention to dependency conflicts when multiple versions coexist, and use a lock file to pin versions
5. Performance pitfalls: Pay attention to performance optimization in large-data scenarios, and avoid common problems such as N+1 queries

Usage workflow

Step 1: Environment preparation

Ensure the necessary dependencies and tools are installed in the development environment.

Step 2: Configuration initialization

Perform basic configuration according to project requirements.

Step 3: Using core features

Implement the core features according to the sample code.

Step 4: Testing and verification

Run tests to ensure the functionality works properly.

Step 5: Deployment and release

After development is complete, deploy and monitor.