java-conventions

Files (1)

• SKILL.md

SKILL.md (first lines)

# Java Conventions

## Java Version

- Assume projects target at least Java 17. There is no need to worry about backwards compability with older Java releases
- Determine a project's Java language level, based on build tool settings, or existing usages.
- Use Java 25 syntax and API language features, when a project is already using Java 25.

## Syntax

- Use [pattern-matching `instanceof`](https://errorprone.info/bugpattern/PatternMatchingInstanceof) when possible
- **NEVER** use fully qualified class names; ALWAYS add any required missing imports instead;
  e.g. generate code using `new HashMap<>();` instead of `new java.util.HashMap<>();` etc.

## Testing

- If the project uses modern JUnit v5 (Jupiter) API, then do not prefix JUnit @Test methods with `test`, just use a descriptive name without the prefix.
  Do use `test` prefixes on projects with older JUnit versions which still required this.
- Use Google Truth instead of JUnit's own (or any other) assertions, where possible.
  For testing that exceptions are thrown, use `org.junit.jupiter.api.Assertions.assertThrows` because Google Truth doesn't have an equivalent.
- Always annotate methods (whether `static` or not) with `@VisibleForTesting` (`com.google.common.annotations.VisibleForTesting`) whenever they are not marked `private` (e.g. package-private) so that they can be tested.
- Refer to the `testing` skill for how to execute the tests for the project.

## Structure

- Name unused variables `_` instead of `unused`
- Use `var` for local variable declarations where the type is obvious from the right-hand side
- Every new package must contain a package-info.java file with a package description and @NullMarked.

## Logging

- Use SLF4j API for logging
- Never use `System.err.println()` or `e.printStackTrace()`. Use a SLF4j logger instead, add it if it's missing.
- Logger should never be constructor injected, but always simply be a static final field.

## Guava

- Use Guava's Immutable Collections instead of Java Collections Framework where appropriate
- Use Guava utilities instead of JDK equivalents where appropriate
- Use Guava's `Strings.isNullOrEmpty()` instead of `string == null || string.isBlank()`

## Jackson

- Because we always compile with -parameters, we typically do not need to add any @JsonCreator or @JsonProperty
  annotations - except on both interfaces and for enum values, where they ARE required. (If a project's build
  tool configuration is missing whatever that tool's way to use `-parameters` is, then enable it.)

## Library Documentation and API Discovery

When you need to look up public APIs, method signatures, Javadocs, or usage examples for external Java libraries (such as Maven Central dependencies):

1. **Context7 MCP**: First use the `resolve-library-id` and `query-docs` MCP tools to find documentation, code snippets, and usage patterns.
2. **javadoc.io**: Use `read_url_content` to fetch class documentation from `https://www.javadoc.io/static/<groupId>/<artifactId>/<version>/...` (e.g. `allclasses-index.html`, package summaries, or class Javadocs).
3. **Source Inspection**: If you need to understand internal implementation details, look for the `-sources.jar` or view the upstream GitHub repository (via GitHub MCP or web).
4. **Bytecode Disassembly Anti-pattern**: **NEVER** run `javap` or complex `grep` pipelines against cached `.jar` files in `~/.gradle/caches` to discover Java APIs or method signatures.

## Other

- Uses ErrorProne for static analysis; follow it recommendations
- Uses JSpecify annotations for nullability (`@Nullable`, `@NonNull`).
  Always replace any existing `javax.annotation` with it.

From vorburger/aifiles, CC-BY-4.0.

More from vorburger/aifiles