Add docs/JAVA.md with Java-specific guidance#2974
Conversation
Co-authored-by: afranken <763000+afranken@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Adds a canonical Java style/idioms guide to complement the existing Kotlin guidance, and links it from the main contributor agent context so Java changes (notably in testsupport/) have a consistent reference.
Changes:
- Added
docs/JAVA.mdwith Java-specific style, naming, test naming, and Javadoc guidance derived from the project’s Checkstyle configuration. - Updated
AGENTS.mdto reference the new Java guidelines alongsidedocs/KOTLIN.md.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/JAVA.md | Introduces Java guidelines (style + idioms + anti-patterns + naming + tests + Javadoc). |
| AGENTS.md | Links the new Java guidelines from the project’s Code Style section. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | Anti-Pattern | Refactor To | | ||
| |---|---| | ||
| | `list.size() == 0` | `list.isEmpty()` | | ||
| | `Collections.emptyList()` | `List.of()` | | ||
| | `Collections.unmodifiableList(new ArrayList<>(...))` | `List.copyOf(...)` | | ||
| | `"" + value` | `String.valueOf(value)` or `String.format(...)` | | ||
| | Empty catch blocks | At minimum, log the exception | | ||
| | Magic numbers/strings | Named constants | |
There was a problem hiding this comment.
The anti-patterns table is not valid Markdown because the rows start with || instead of |. This will render incorrectly on GitHub; use a single leading pipe for each row (header, separator, and body).
| - **Indentation**: 2 spaces (no tabs) | ||
| - **Line length**: 120 characters maximum | ||
| - **Braces**: Always use braces for `if`, `for`, `while`, `do` blocks | ||
| - **Imports**: Static imports first, then third-party packages; alphabetical within groups; no wildcard imports |
There was a problem hiding this comment.
The import-order guidance here doesn’t match the enforced Checkstyle config: CustomImportOrder is configured as STATIC###THIRD_PARTY_PACKAGE, which effectively means “static imports first, then all non-static imports” (no separate standard/third-party grouping). Consider rewording this bullet to reflect the actual rule to avoid confusion.
| - **Imports**: Static imports first, then third-party packages; alphabetical within groups; no wildcard imports | |
| - **Imports**: Static imports first, then all non-static imports; alphabetical within each group; no wildcard imports |
| - Use `List.of(...)`, `Map.of(...)` for immutable collections instead of `Collections.unmodifiableList(...)` | ||
| - Prefer streams over explicit loops for transformations: | ||
| ```java | ||
| buckets.stream().map(Bucket::name).collect(Collectors.toSet()) |
There was a problem hiding this comment.
This Java snippet is missing a trailing semicolon, so it isn’t a copy/pasteable example. Consider updating it to a syntactically complete statement (and optionally include/import Collectors if you want it to compile standalone).
| buckets.stream().map(Bucket::name).collect(Collectors.toSet()) | |
| buckets.stream().map(Bucket::name).collect(Collectors.toSet()); |
Java code exists in the project (testsupport modules) but had no canonical style reference, unlike Kotlin which has
docs/KOTLIN.md.Changes
docs/JAVA.md— New Java guidelines document mirroring the structure ofdocs/KOTLIN.md:etc/checkstyle.xml): 2-space indent, 120-char line limit, mandatory braces, import orderingvar,List.of(), streams, switch expressions, text blocksKOTLIN.md)AGENTS.md— Added reference todocs/JAVA.mdin the Code Style section alongside the existingdocs/KOTLIN.mdreferenceOriginal prompt
🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.