java-best-practices

name	java-best-practices
description	Use this skill when generating or reviewing Java code to ensure readability, maintainability, correctness, and modern best practices.

Java Best Practices

Scope

Apply this skill when working on:

• service and domain logic
• utility classes
• refactoring existing code
• general Java design and structure

---

Code clarity and readability

• Use intention-revealing names for classes, methods, and variables.
• Keep methods small and focused on a single responsibility.
• Avoid deep nesting; prefer early returns.
• Prefer readability over clever or overly compact code.

---

Null safety

• Avoid NullPointerException risks in chained calls.
• Prefer Optional for nullable return values.
• Return empty collections instead of null.
• Validate inputs explicitly.

---

Exception handling

• Do not swallow exceptions.
• Avoid catching overly broad exceptions (Exception, Throwable).
• Always preserve the original cause when rethrowing.
• Log with context and stack trace.

---

Separation of concerns

• Keep business logic separate from persistence and transport layers.
• Avoid large “god classes”.
• Keep classes cohesive and focused.

---

Collections and streams

• Do not modify collections while iterating.
• Use streams for transformations, loops for side effects.
• Avoid unnecessary stream usage in tight loops.
• Be explicit about mutability when collecting results.

---

Dependency and design principles

• Prefer constructor injection.
• Make dependencies explicit.
• Avoid hidden or implicit dependencies.
• Design classes for clarity and testability.

---

Resource management

• Use try-with-resources for AutoCloseable resources.
• Ensure all I/O and database resources are properly closed.

---

Concurrency awareness

• Avoid shared mutable state when possible.
• Use thread-safe collections when needed.
• Prefer immutable objects.
• Be careful with async and multi-threaded code.

---

Performance awareness

• Avoid obvious performance anti-patterns:
  • string concatenation in loops
  • repeated regex compilation
  • unnecessary object creation in hot paths
• Prefer readability first; optimize only when necessary.
• Measure before optimizing.

---

Refactoring mindset

• Refactor when duplication appears.
• Simplify complex logic into smaller units.
• Improve naming and structure when readability suffers.
• Prefer incremental improvements.

---

Testability

• Write code that is easy to test.
• Avoid tight coupling.
• Keep business logic independent from frameworks when possible.
• Prefer deterministic behavior.

---

Output expectations

When generating or refactoring code:

• prioritize clarity and maintainability
• avoid unnecessary abstraction
• follow modern Java idioms
• improve existing code where possible
• explain non-obvious improvements briefly