Skip to main content
Agent skill

Java Coding Standards

Java coding standards for Spring Boot and Quarkus services: naming, immutability, Optional usage, streams, exceptions, generics, CDI, reactive patterns, and project layout. Automatically applies framework-specific conventions. Use when writing or reviewing Java in a Spring Boot or Quarkus service.

Get started

Get the complete skill folder, including its scripts and reference files.

·

When to use this skill

Use Java Coding Standards when an AI agent needs a reusable SKILL.md workflow for this job: Java coding standards for Spring Boot and Quarkus services: naming, immutability, Optional usage, streams, exceptions, generics, CDI, reactive patterns, and project layout. Automatically applies framework-specific conventions. Use when writing or reviewing Java in a Spring Boot or Quarkus service.

When not to use it

Skip Java Coding Standards when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/java-coding-standards
# Save SKILL.md to ~/.claude/skills/java-coding-standards/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/java-coding-standards/SKILL.md. For a shared project, commit the folder at .claude/skills/java-coding-standards/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Java Coding Standards skill for this task: Writing or reviewing Java code in Spring Boot or Quarkus projects. Confirm any required inputs or files before making changes.

What supports this recommendation?

83/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
92/100
Practical detail
92/100
Source evidence
63/100
Source signals
70/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Java Coding Standards

Standards for readable, maintainable Java (17+) code in Spring Boot and Quarkus services.

## When to Use

- Writing or reviewing Java code in Spring Boot or Quarkus projects - Enforcing naming, immutability, or exception handling conventions - Working with records, sealed classes, or pattern matching (Java 17+) - Reviewing use of Optional, streams, or generics - Structuring packages and project layout - **[QUARKUS]**: Working with CDI scopes, Panache entities, or reactive pipelines

## How It Works

### Framework Detection

Before applying standards, determine the framework from the build file:

- Build file contains `quarkus` → apply **[QUARKUS]** conventions - Build file contains `spring-boot` → apply **[SPRING]** conventions - Neither detected → apply shared conventions only

## Core Principles

- Prefer clarity over cleverness - Immutable by default; minimize shared mutable state - Fail fast with meaningful exceptions - Consistent naming and package structure - **[QUARKUS]**: Favor build-time over runtime processing; avoid runtime reflection where possible

## Examples

The sections below show concrete Spring Boot, Quarkus, and shared Java examples for naming, immutability, dependency injection, reactive code, exceptions, project layout, logging, configuration, and tests.

## Naming

```java // PASS: Classes/Records: PascalCase public class MarketService {} public record Money(BigDecimal amount, Currency currency) {}

// PASS: Methods/fields: camelCase private final MarketRepository marketRepository; public Market findBySlug(String slug) {}

// PASS: Constants: UPPER_SNAKE_CASE private static final int MAX_PAGE_SIZE = 100;

// PASS: [QUARKUS] JAX-RS resources named as *Resource, not *Controller public class MarketResource {}

// PASS: [SPRING] REST controllers named as *Controller public class MarketController {} ```

## Immutability

```java // PASS: Favor records and final fields public record MarketDto(Long id, String name, MarketStatus status) {}

public class Market { private final Long id; private final String name; // getters only, no setters }

// PASS: [QUARKUS] Panache active-record entities use public fields (Quarkus convention) @Entity public class Market extends PanacheEntity { public String name; public MarketStatus status; // Panache generates accessors at build time; public fields are idiomatic here }

// PASS: [QUARKUS] Panache MongoDB entities @MongoEntity(collection = "markets") public class Market extends PanacheMongoEntity { public String name; public MarketStatus status; } ```

## Optional Usage

```java // PASS: Return Optional from find* methods // [SPRING] Optional<Market> market = marketRepository.findBySlug(slug);

// [QUARKUS] Panache Optional<Market> market = Market.find("slug", slug).firstResultOptional();

// PASS: Map/flatMap instead of get() return market .map(MarketResponse::from) .orElseThrow(() -> new EntityNotFoundException("Market not found")); ```

## Streams Best Practices

```java // PASS: Use streams for transformations, keep pipelines short List<String> names = markets.stream() .map(Market::name) .filter(Objects::nonNull) .toList();

// FAIL: Avoid complex nested streams; prefer loops for clarity ```

## Dependency Injection

```java // PASS: [SPRING] Constructor injection (preferred over @Autowired on fields) @Service public class MarketService { private final MarketRepository marketRepository;

public MarketService(MarketRepository marketRepository) { this.marketRepository = marketRepository; } }

// PASS: [QUARKUS] Constructor injection @ApplicationScoped public class MarketService { private final MarketRepository marketRepository;

@Inject public MarketService(MarketRepository marketRepository) { this.marketRepository = marketRepository; } }

// PASS: [QUARKUS] Package-private field injection (acceptable in Quarkus — avoids proxy issues) @ApplicationScoped public class MarketService { @Inject MarketRepository marketRepository; }

// FAIL: [SPRING] Field injection with @Autowired @Autowired private MarketRepository marketRepository; // use constructor injection

// FAIL: [QUARKUS] @Singleton when interception or lazy init is needed @Singleton // non-proxyable — use @ApplicationScoped instead public class MarketService {} ```

## Reactive Patterns [QUARKUS]

```java // PASS: Return Uni/Multi from reactive endpoints @GET @Path("/{slug}") public Uni<Market> findBySlug(@PathParam("slug") String slug) { return Market.find("slug", slug) .<Market>firstResult() .onItem().ifNull().failWith(() -> new MarketNotFoundException(slug)); }

// PASS: Non-blocking pipeline composition public Uni<OrderConfirmation> placeOrder(OrderRequest req) { return validateOrder(req) .chain(valid -> persistOrder(valid)) .chain(order -> notifyFulfillment(order)); }

// FAIL: Blocking call inside a Uni/Multi pipeline public Uni<Market> find(String slug) { Market m = Market.find("slug", slug).firstResult(); // BLOCKING — breaks event loop return Uni.createFrom().item(m); }

// FAIL: Subscribing more than once to a shared Uni Uni<Market> shared = fetchMarket(slug); shared.subscribe().with(m -> log(m)); shared.subscribe().with(m -> cache(m)); // double subscribe — use Uni.memoize() ```

## Exceptions

- Use unchecked exceptions for domain errors; wrap technical exceptions with context - Create domain-specific exceptions (e.g., `MarketNotFoundException`) - Avoid broad `catch (Exception ex)` unless rethrowing/logging centrally

```java throw new MarketNotFoundException(slug); ```

### Centralised Exception Handling

```java // [SPRING] @RestControllerAdvice public class GlobalExceptionHandler { @ExceptionHandler(MarketNotFoundException.class) public ResponseEntity<ErrorResponse> handle(MarketNotFoundException ex) { return ResponseEntity.status(404).body(ErrorResponse.from(ex)); } }

// [QUARKUS] Option A: ExceptionMapper @Provider public class MarketNotFoundMapper implements ExceptionMapper<MarketNotFoundException> { @Override public Response toResponse(MarketNotFoundException ex) { return Response.status(404).entity(ErrorResponse.from(ex)).build(); } }

// [QUARKUS] Option B: @ServerExceptionMapper (RESTEasy Reactive) @ServerExceptionMapper public RestResponse<ErrorResponse> handle(MarketNotFoundException ex) { return RestResponse.status(Status.NOT_FOUND, ErrorResponse.from(ex)); } ```

## Generics and Type Safety

- Avoid raw types; declare generic parameters - Prefer bounded generics for reusable utilities

```java public <T extends Identifiable> Map<Long, T> indexById(Collection<T> items) { ... } ```

## Project Structure

### [SPRING] Maven/Gradle

``` src/main/java/com/example/app/ config/ controller/ service/ repository/ domain/ dto/ util/ src/main/resources/ application.yml src/test/java/... (mirrors main) ```

### [QUARKUS] Maven/Gradle

``` src/main/java/com/example/app/ config/ # @ConfigMapping, @ConfigProperty beans, Producers resource/ # JAX-RS resources (not "controller") service/ repository/ # PanacheRepository implementations (if not using active record) domain/ # JPA/Panache entities, MongoDB entities dto/ util/ mapper/ # MapStruct mappers (if used) src/main/resources/ application.properties # Quarkus convention (YAML supported with quarkus-config-yaml) import.sql # Hibernate auto-import for dev/test src/test/java/... (mirrors main) ```

## Formatting and Style

- Use 2 or 4 spaces consistently (project standard) - One public top-level type per file - Keep methods short and focused; extract helpers - Order members: constants, fields, constructors, public methods, protected, private

## Code Smells to Avoid

- Long parameter lists → use DTO/builders - Deep nesting → early returns - Magic numbers → named constants - Static mutable state → prefer dependency injection - Silent catch blocks → log and act or rethrow - **[QUARKUS]**: `@Singleton` where `@ApplicationScoped` is intended — breaks proxying and interception - **[QUARKUS]**: Mixing `quarkus-resteasy-reactive` and `quarkus-resteasy` (classic) — pick one stack - **[QUARKUS]**: Panache active-record + repository pattern in the same bounded context — pick one

## Logging

```java // [SPRING] SLF4J private static final Logger log = LoggerFactory.getLogger(MarketService.class); log.info("fetch_market slug={}", slug); log.error("failed_fetch_market slug={}", slug, ex);

// [QUARKUS] JBoss Logging (default, zero-cost at build time) private static final Logger log = Logger.getLogger(MarketService.class); log.infof("fetch_market slug=%s", slug); log.errorf(ex, "failed_fetch_market slug=%s", slug);

// [QUARKUS] Alternative: simplified logging with @Inject @Inject Logger log; // CDI-injected, scoped to declaring class ```

## Null Handling

- Accept `@Nullable` only when unavoidable; otherwise use `@NonNull` - Use Bean Validation (`@NotNull`, `@NotBlank`) on inputs - **[QUARKUS]**: Apply `@Valid` on `@BeanParam`, `@RestForm`, and request body parameters

## Configuration

```java // [SPRING] @ConfigurationProperties @ConfigurationProperties(prefix = "market") public record MarketProperties(int maxPageSize, Duration cacheTtl) {}

// [QUARKUS] @ConfigMapping (type-safe, build-time validated) @ConfigMapping(prefix = "market") public interface MarketConfig { int maxPageSize(); Duration cacheTtl(); }

// [QUARKUS] Simple values with @ConfigProperty @ConfigProperty(name = "market.max-page-size", defaultValue = "100") int maxPageSize; ```

## Testing Expectations

### Shared - JUnit 5 + AssertJ for fluent assertions - Mockito for mocking; avoid partial mocks where possible - Favor deterministic tests; no hidden sleeps

### [SPRING] - `@WebMvcTest` for controller slices, `@DataJpaTest` for repository slices - `@SpringBootTest` reserved for full integration tests - `@MockBean` for replacing beans in Spring context

### [QUARKUS] - Plain JUnit 5 + Mockito for unit tests (no `@QuarkusTest`) - `@QuarkusTest` reserved for CDI integration tests - `@InjectMock` for replacing CDI beans in integration tests - Dev Services for database/Kafka/Redis — avoid manual Testcontainers setup when Dev Services suffice - `@QuarkusTestResource` for custom external service lifecycle

```java // [SPRING] Controller test @WebMvcTest(MarketController.class) class MarketControllerTest { @Autowired MockMvc mockMvc; @MockBean MarketService marketService; }

// [QUARKUS] Integration test @QuarkusTest class MarketResourceTest { @InjectMock MarketService marketService;

@Test void should_return_404_when_market_not_found() { given().when().get("/markets/unknown").then().statusCode(404); } }

// [QUARKUS] Unit test (no CDI, no @QuarkusTest) @ExtendWith(MockitoExtension.class) class MarketServiceTest { @Mock MarketRepository marketRepository; @InjectMocks MarketService marketService; } ```

**Remember**: Keep code intentional, typed, and observable. Optimize for maintainability over micro-optimizations unless proven necessary.

Intended uses

  • Writing or reviewing Java code in Spring Boot or Quarkus projects
  • Enforcing naming, immutability, or exception handling conventions
  • Working with records, sealed classes, or pattern matching (Java 17+)
  • Reviewing use of Optional, streams, or generics
  • Structuring packages and project layout
  • [QUARKUS]: Working with CDI scopes, Panache entities, or reactive pipelines

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.