Java Style Guide Overview

General Principles

The Essencium Backend follows standard Java conventions and Spring Boot best practices. This guide outlines the coding standards and conventions used throughout the project.

Code Organization

Package Structure

• Use meaningful package names that reflect the functionality
• Follow domain-driven design principles
• Separate concerns into distinct packages:
  • controller - REST controllers
  • service - Business logic
  • repository - Data access
  • model - Domain entities
  • dto - Data transfer objects
  • configuration - Spring configuration
  • security - Security-related classes
  • util - Utility classes

Class Naming

• Use PascalCase for class names
• Be descriptive and avoid abbreviations
• Suffix classes appropriately:
  • *Controller for REST controllers
  • *Service for service classes
  • *Repository for repositories
  • *Dto for DTOs
  • *Representation for API responses
  • *Configuration for configuration classes

Lombok Usage

Lombok is used extensively across model, DTO, representation, and configuration classes to reduce boilerplate. The conventions in use:

• @Data is used on entities, DTOs, and configuration property classes (Role, Right, AbstractBaseModel, BaseUserDto, AppCorsProperties, …). This is the project’s default for value-style classes.
• @SuperBuilder (not plain @Builder) on classes that participate in inheritance — e.g. anything extending AbstractBaseModel or AbstractBaseUser.
• @NoArgsConstructor + @AllArgsConstructor paired with @Data / @SuperBuilder so JPA, Jackson, and the builder all have the constructors they need.
• @RequiredArgsConstructor on services and controllers, with private final fields — the project favours constructor injection.
• @Slf4j for logging instead of declaring a Logger field.

Two existing entities (Translation, ApiToken) use individual @Getter / @Setter instead of @Data because their equality/hashCode behaviour needs to be hand-written. Reach for the same pattern only if @Data’s default equals/hashCode would be wrong for your class — otherwise stay on @Data.

Spring Boot Conventions

Dependency Injection

• Prefer constructor injection over field injection
• Use @RequiredArgsConstructor with final fields
• Avoid @Autowired on fields

Annotations

• Place annotations on separate lines for readability
• Order: Spring annotations, then JPA, then Lombok
• Document complex configurations with comments

Method Design

Single Responsibility

• Each method should do one thing well
• Keep methods short (< 20 lines preferred)
• Extract complex logic into private helper methods

Naming

• Use descriptive verb-based names
• Follow Java conventions (camelCase)
• Boolean methods should start with is, has, or can

Error Handling

• Use appropriate exception types
• Create custom exceptions for domain-specific errors
• Always log errors with appropriate levels
• Return meaningful error messages to clients

Testing

• Write unit tests for all business logic
• Use descriptive test method names
• Follow AAA pattern (Arrange, Act, Assert)
• Mock external dependencies

Documentation

• Use Javadoc for public APIs
• Document complex business logic
• Keep documentation up-to-date
• Use @Operation annotations for REST endpoints