awesome-copilot/instructions/java.instructions.md

description	applyTo
Guidelines for building Java base applications	**/*.java

Java Development

General Instructions

• First, prompt the user if they want to integrate static analysis tools (SonarQube, PMD, Checkstyle) into their project setup. If yes, provide guidance on tool selection and configuration.
• If the user declines static analysis tools or wants to proceed without them, continue with implementing the Best practices, bug patterns and code smell prevention guidelines outlined below.
• Address code smells proactively during development rather than accumulating technical debt.
• Focus on readability, maintainability, and performance when refactoring identified issues.
• Use IDE / Code editor reported warnings and suggestions to catch common patterns early in development.

Best practices

• Records: For classes primarily intended to store data (e.g., DTOs, immutable data structures), Java Records should be used instead of traditional classes.
• Pattern Matching: Utilize pattern matching for instanceof and switch expression to simplify conditional logic and type casting.
• Type Inference: Use var for local variable declarations to improve readability, but only when the type is explicitly clear from the right-hand side of the expression.
• Immutability: Favor immutable objects. Make classes and fields final where possible. Use collections from List.of()/Map.of() for fixed data. Use Stream.toList() to create immutable lists.
• Streams and Lambdas: Use the Streams API and lambda expressions for collection processing. Employ method references (e.g., stream.map(Foo::toBar)).
• Null Handling: Avoid returning or accepting null. Use Optional<T> for possibly-absent values and Objects utility methods like equals() and requireNonNull().

Naming Conventions

• Follow Google's Java style guide:
  • UpperCamelCase for class and interface names.
  • lowerCamelCase for method and variable names.
  • UPPER_SNAKE_CASE for constants.
  • lowercase for package names.
• Use nouns for classes (UserService) and verbs for methods (getUserById).
• Avoid abbreviations and Hungarian notation.

Bug Patterns

Rule ID	Description	Example / Notes
S2095	Resources should be closed	Use try-with-resources when working with streams, files, sockets, etc.
S1698	Objects should be compared with .equals() instead of ==	Especially important for Strings and boxed primitives.
S1905	Redundant casts should be removed	Clean up unnecessary or unsafe casts.
S3518	Conditions should not always evaluate to true or false	Watch for infinite loops or if-conditions that never change.
S108	Unreachable code should be removed	Code after return, throw, etc., must be cleaned up.

Code Smells

Rule ID	Description	Example / Notes
S107	Methods should not have too many parameters	Refactor into helper classes or use builder pattern.
S121	Duplicated blocks of code should be removed	Consolidate logic into shared methods.
S138	Methods should not be too long	Break complex logic into smaller, testable units.
S3776	Cognitive complexity should be reduced	Simplify nested logic, extract methods, avoid deep if trees.
S1192	String literals should not be duplicated	Replace with constants or enums.
S1854	Unused assignments should be removed	Avoid dead variables—remove or refactor.
S109	Magic numbers should be replaced with constants	Improves readability and maintainability.
S1188	Catch blocks should not be empty	Always log or handle exceptions meaningfully.

Build and Verification

• After adding or modifying code, verify the project continues to build successfully.
• If the project uses Maven, run mvn clean install.
• If the project uses Gradle, run ./gradlew build (or gradlew.bat build on Windows).
• Ensure all tests pass as part of the build.