java.md

Java Conventions

• Use package-by-feature organization.
• Do not create global top-level dto, repository, service, web, or storage packages.
• Use 4-space indentation.
• Use PascalCase for classes and camelCase for fields and methods.
• Avoid wildcard imports.
• Prefer constructor injection for Spring beans.
• Use Java records for DTOs and immutable value objects when practical.
• Keep REST resources thin; delegate behavior to services.
• Keep domain logic in catalog, validation, visualization, selection, or export, not in shared.
• Do not introduce JPA, repositories backed by a database, Liquibase, Spring Security, or user/session persistence unless a later phase explicitly requires it.
• Do not inject EntityManager or EntityManagerFactory.
• Use controlled exceptions for model loading and integrity failures instead of raw parser errors leaking to API callers.
• Keep server services dependent on FeatureModelStore, not directly on JSON files.
• Prefer intention-revealing method and variable names over terse names.
• Keep methods small and focused on one action. Split validation, mapping, warning creation, and message construction into named helper methods when a method starts doing multiple things.
• Avoid long stream/lambda chains when they make control flow hard to read. Use clear local variables and ordinary loops for multi-step validation or tree traversal logic.
• Avoid horizontally long lines and deeply chained assertions or method calls. Break complex statements into named local variables.
• Define constants for repeated literal values. Use private static final by default and expose constants only when another class genuinely needs them.
• Use the least possible access level for fields, methods, and constants. Increase visibility only when there is a concrete caller outside the class.
• Keep methods ordered from higher-level behavior to lower-level helpers, following the order in which they are used where practical.
• Add Javadoc for server-side methods and constructors. Each Javadoc should include a short description, @param for every parameter, @return for non-void methods, and @throws for exceptions the method can throw.
• Comments and Javadocs must be in English and should clarify intent or non-obvious behavior. Do not add comments that merely repeat the code.
• For the feature-model server, document structural validation assumptions, such as root and group nodes being active paths even though users cannot toggle them.
• Keep DTO conversion methods explicit and local to the owning DTO. Do not expose domain records directly from REST resources.