Instruction file imported from karlkyck/humansreadcode-springboot-exemplar (.github/instructions/java.instructions.md). Copyright stays with the author.

applyTo: "**/*.java" description: "Java development best practices for Spring Boot applications"

Java Development Guidelines

Modern Java Features (Java 21)

• Records: Use records for DTOs and immutable data structures instead of traditional classes
• Pattern Matching: Utilize pattern matching for instanceof and switch expressions
• Type Inference: Use var for local variables when type is clear from context
• Text Blocks: Use text blocks for multi-line strings, especially SQL queries
• Sealed Classes: Use sealed classes for restricted inheritance hierarchies

Code Quality Standards

Naming Conventions

• Use UpperCamelCase for class and interface names
• Use lowerCamelCase for method and variable names
• Use UPPER_SNAKE_CASE for constants
• Use descriptive names that explain purpose, not implementation
• Avoid abbreviations and Hungarian notation

Best Practices

• Immutability: Favor immutable objects and make fields final where possible
• Null Handling: Use Optional<T> for possibly-absent values, avoid returning null
• Streams and Lambdas: Use Streams API for collection processing and method references
• Exception Handling: Use specific exception types and provide meaningful messages
• Resource Management: Use try-with-resources for automatic resource cleanup

Common Patterns to Avoid

• Resource Leaks: Always close resources (files, sockets, streams)
• Equality Issues: Use .equals() or Objects.equals() for object comparison
• Magic Numbers: Replace numeric literals with named constants
• Deep Nesting: Extract methods to reduce cognitive complexity
• Unused Code: Remove unused variables and dead code

Dependency Management

• Use constructor injection for required dependencies
• Declare dependency fields as private final
• Avoid circular dependencies between classes
• Use factory methods for complex object creation
• Prefer composition over inheritance

Testing Guidelines

• Write unit tests for all public methods
• Use meaningful test method names that describe the scenario
• Follow Arrange-Act-Assert pattern
• Mock external dependencies
• Use test data builders for complex objects

Build and Verification

• Run ./gradlew build to verify project builds successfully
• Ensure all tests pass before committing code
• Use static analysis tools when available (SonarQube, SpotBugs)
• Follow code formatting standards consistently