writing-java-kotlin

Java and Kotlin Development

Use only for Java/Kotlin JVM code and JVM build files. Follow the project's JDK, Kotlin, Gradle/Maven, framework, test stack, formatter, static-analysis config, and local conventions.

Read First

Read principles.md before writing, changing, or reviewing Java/Kotlin code. Read conditional references only when the change touches that area.

Conditional References

• patterns.md — package/module layout, Spring/Ktor/service boundaries, nullability, concurrency, persistence, and build seams.
• testing.md — adding or reshaping JUnit, Kotest, Mockito/MockK, Spring, or Gradle/Maven tests; keep the local loop fast.
• linting.md — Gradle/Maven toolchains, formatters, ktlint, detekt, Spotless, and slow-check policy.
• cli.md — writing or changing JVM CLIs.

Project Baseline

• Inspect gradle/wrapper/gradle-wrapper.properties, settings.gradle*, build.gradle*, pom.xml, .mvn/, gradle.properties, CI, and nearby code before using version-specific Java, Kotlin, or plugin behavior.
• Prefer the project wrapper: ./gradlew before global gradle; ./mvnw before global mvn.
• Use the configured Java toolchain and Kotlin jvmToolchain. Do not assume the shell's newest JDK is the compile target.
• Prefer the JDK/Kotlin stdlib and existing dependencies before adding a library.
• Keep domain code free of framework, persistence, HTTP, and DI types unless the project already chose that coupling.

Version-Gated APIs

• Java 21+: records, sealed types, pattern matching, switch expressions, and virtual threads are available when the project toolchain allows them.
• Java 25+: treat new platform APIs as available only when Gradle/Maven toolchains and CI target 25 or newer.
• Preview features require explicit user or project approval and a visible compiler/test flag.
• Kotlin: follow the configured Kotlin language/API version. Do not use a Kotlin 2.x feature unless the build already enables it.

Comments, Javadoc, and KDoc

• Use Javadoc or KDoc for visible public APIs when the project expects generated docs.
• Keep API docs to a useful summary, contract, edge case, or effect. Do not restate names and signatures.
• Omit comments for simple obvious getters, overrides, and data holders when there is nothing useful to add.
• Add implementation comments only for non-obvious constraints, invariants, side effects, tradeoffs, or framework quirks.
• Keep comments short. Move longer rationale to docs, issue links, or design notes.
• Do not comment obvious code.
• Keep tests readable without comments; add one only for unobvious fixtures, timing, concurrency, framework setup, or regression context.

Verification

Run focused module tests and format/lint while editing, then the project-configured build, tests, lint, static analysis, and formatting checks before final output. Prefer Gradle/Maven test filtering over full-suite runs in the hot loop.

If a check is unavailable, state that and run the closest configured gate. If a check fails, quote the failure, diagnose the cause, fix one issue, and rerun the relevant check.

Failure Cases

• No clear JVM root: locate the nearest settings.gradle*, build.gradle*, or pom.xml before choosing commands or package names.
• Unknown JDK or Kotlin target: inspect toolchains, compiler options, CI, and wrapper versions before using newer APIs or syntax.
• New dependency requested: confirm the JDK/Kotlin stdlib or existing dependencies cannot meet the requirement.
• Slow checks by default: switch to focused Gradle/Maven filters or file-scoped format/lint; reserve broad checks for final verification.
• Broad or risky edit: state the risk and ask before acting. Do not run destructive commands.

Final Response

Include:

• changed files
• checks run and results
• checks skipped with reasons
• remaining risks or follow-ups