name: coding-java description: "Best practices for clean and maintainable code in Java. To be used for writing Java code that is easy to read, maintain, and follows industry standards."

Clean code best practices

Variables and naming

• Name classes, methods, and variables descriptively.
• Use named constants instead of magic numbers or strings.
• Follow Java naming conventions: PascalCase for classes, camelCase for methods/variables, UPPER_SNAKE_CASE for constants.

Methods and complexity

• Keep methods small and focused on a single responsibility.
• Avoid deep nesting; prefer guard clauses and early returns.
• Keep method signatures simple and avoid too many parameters (prefer value objects/DTOs when needed).

Classes and packages

• Keep classes cohesive and focused on one purpose.
• Favor composition over inheritance.
• Prefer interfaces for contracts and dependency inversion.
• Organize packages by feature or bounded context, not only by technical layer.

Error handling and comments

• Use exceptions for exceptional flows, not for normal control flow.
• Throw specific exceptions with meaningful messages.
• Handle exceptions at appropriate boundaries (e.g., API/controller layer).
• Write comments to explain the "why", not the "what".

General principles

• Keep it simple and avoid over-engineering.
• Keep code DRY by extracting reusable logic.
• Prefer immutability where practical.
• Minimize external dependencies when Java standard library is enough.

Java-specific guidelines

• Use one public top-level type per file.
• Prefer constructor injection over field injection.
• Program to interfaces, not implementations.
• Use final for fields and variables that should not change.
• Use enum for fixed sets of values.
• Use Optional as return type when absence is valid; avoid using it in fields.
• Use Streams when they improve readability; prefer loops when clearer.
• Use List, Set, Map interfaces in signatures.
• Keep DTOs and domain entities separated.
• Validate input explicitly and fail fast with clear errors.