/java-programmer

name: java-programmer
description: Java-specific tooling, documentation standards, testing practices, and modern idioms. Use when working with Java code or Java-based projects on the JVM.

Java Programmer

Purpose

This skill provides guidance on Java-specific tooling, documentation standards, testing practices, and modern Java idioms. Java is a statically-typed, object-oriented language with a massive ecosystem and strong backwards compatibility guarantees. This skill focuses on navigating the Java ecosystem effectively, writing maintainable Java code, and applying functional programming concepts within Java's constraints.

When to Use This Skill

Use this skill when:

• Working with Java codebases (any version, but especially Java 8+)
• Making decisions about build tools, testing frameworks, or dependencies
• Writing Javadoc documentation
• Writing JUnit tests
• Applying functional programming patterns in Java
• Navigating the JVM ecosystem (choosing between JVM languages)

<core_philosophy>

Core Philosophy

**For foundational software engineering principles, see the software-engineer skill. For OOP principles (SOLID, GoF patterns), see the object-oriented-programmer skill.**

Java's Strengths and Constraints

Java excels in specific contexts but has limitations compared to more modern languages.

**Where Java shines:**

• **Enterprise systems** — Mature ecosystem, strong tooling, extensive libraries
• **Team stability** — Explicit types, verbose code, fewer "clever" tricks
• **Long-term maintenance** — Backwards compatibility, gradual evolution
• **JVM ecosystem** — Interop with Kotlin, Scala, Clojure, Groovy
• **Performance** — JIT compilation, mature garbage collectors, profiling tools

**Where Java struggles:**

• **Rapid prototyping** — Verbosity slows iteration
• **Functional programming** — Retrofitted features, verbose syntax
• **Type system** — Lacks algebraic data types, pattern matching (until recent versions)
• **Ceremony** — Boilerplate reduces signal-to-noise ratio

**Staff insight:** If you're writing Java professionally but prefer functional languages, focus on using modern Java features (streams, Optional, lambdas) to bring functional thinking into Java's constraints. Don't fight the language—work within its idioms.

Documentation as Contract

Javadoc is more than comments—it's a contract between API and client. Treat it as seriously as the code itself.

**Quote to remember:** "Code is read more often than written." — Guido van Rossum. Documentation is read even more often than that. </core_philosophy>

<type_annotations>

Type Annotations and The Checker Framework Are Mandatory

Java's type system lacks many important guarantees. Type annotations with The Checker Framework enable compile-time verification of properties that the type system doesn't enforce.

**Why type annotations and static analysis matter:**

• **Critical for LLM-assisted development** — Explicit contracts enable better code generation and reasoning
• Eliminate entire classes of errors at compile time (NullPointerException, regex errors, format string bugs)
• Make API contracts machine-readable (not just documented in Javadoc)
• Enable static analysis to catch bugs before runtime
• Self-documenting code (contracts visible in signatures)

**The Checker Framework is mandatory for all new projects:**

• Use **JSpecify annotations** for nullness (`@Nullable`, `@NonNull` via defaults)
• JSpecify provides multi-tool compatibility (works with Checker Framework, IntelliJ, NullAway, etc.)
• Enable as many Checker Framework checkers as practical:
• **Nullness Checker** (via JSpecify annotations) — Prevent NullPointerException
• **Optional Checker** — Enforce proper Optional usage
• **Regex Checker** — Verify regex string validity at compile time
• **Format String Checker** — Verify printf/format string correctness
• **Interning Checker** — Ensure string interning correctness
• **Index Checker** — Prevent array bounds errors
• **Lock Checker** — Verify lock usage and prevent race conditions
• Additional checkers as applicable to domain

**Example with JSpecify nullness annotations:**

import org.jspecify.annotations.Nullable;
// @NonNull is the default assumption (no annotation needed)

public class UserService {
    /**
     * Finds user by ID.
     *
     * @param id the user ID (must not be null, default assumption)
     * @return user if found, null otherwise
     */
    public @Nullable User findById(String id) {
        // Checker verifies: id cannot be null (default @NonNull)
        // Checker requires: callers handle possible null return
        return repository.findById(id).orElse(null);
    }

    /**
     * Gets user display name.
     *
     * @param user the user (must not be null, default assumption)
     * @return display name (never null, default assumption)
     */
    public String getDisplayName(User user) {
        // Checker verifies: user cannot be null
        // Checker enforces: return value cannot be null
        String name = user.getName();
        return name != null ? name : "Guest";
    }
}

**Example with other Checker Framework annotations:**

import org.checkerframework.checker.regex.qual.Regex;
import org.checkerframework.checker.formatter.qual.FormatMethod;

public class ValidationService {
    /**
     * Validates input against pattern.
     *
     * @param input the input string
     * @param pattern the regex pattern (verified at compile time)
     * @return true if input matches pattern
     */
    public boolean matches(String input, @Regex String pattern) {
        // Checker verifies: pattern is valid regex at compile time
        return input.matches(pattern);
    }

    /**
     * Logs formatted message.
     *
     * @param format the format string (verified at compile time)
     * @param args the format arguments
     */
    @FormatMethod
    public void logFormatted(String format, Object... args) {