aw-spec-cli 0.1.9 → 0.1.11

package/assets/guardrails/technology/java-spring/coding-standards.md

@@ -0,0 +1,821 @@
+# Java Coding Standards
+
+> Pure technology (domain-agnostic).
+>
+> Defines generic Java coding and implementation standards for AppWeaver applications.
+>
+> See also: `dependency-policy.md`, `ai-rules.md`.
+
+---
+
+## 1. Java Version
+
+- The project MUST use the Java version defined by its active build configuration.
+
+- Java 21 SHOULD be the default AppWeaver Java baseline unless the project explicitly defines another supported version.
+
+- The configured Java version MUST be consistent across:
+  - local development;
+  - build configuration;
+  - CI;
+  - testing;
+  - deployment.
+
+- Production code MUST NOT depend on APIs introduced in a newer Java version than the configured project version.
+
+---
+
+## 2. Naming Conventions
+
+### Packages
+
+- Package names MUST use lowercase characters.
+
+- Package names MUST follow standard Java naming conventions.
+
+### Classes and Interfaces
+
+- Classes, interfaces, records, enums, and annotations MUST use `PascalCase`.
+
+Examples:
+
+```text
+Booking
+CreateBookingUseCase
+BookingResponse
+BookingStatus
+````
+
+### Methods and Variables
+
+* Methods, fields, parameters, and local variables MUST use `camelCase`.
+
+Examples:
+
+```text
+createBooking()
+bookingId
+customerName
+flightNumber
+```
+
+### Constants
+
+* Constants MUST use `UPPER_SNAKE_CASE`.
+
+Example:
+
+```java
+private static final int MAX_RETRY_COUNT = 3;
+```
+
+### Boolean Names
+
+Boolean variables and methods SHOULD use meaningful prefixes such as:
+
+```text
+is
+has
+can
+should
+```
+
+Examples:
+
+```text
+isActive
+hasPermission
+canRetry
+```
+
+---
+
+## 3. Type Safety
+
+* Production code MUST be type-safe.
+
+* Raw types are forbidden.
+
+* Unchecked casts SHOULD be avoided.
+
+* Unchecked compiler warnings SHOULD be eliminated.
+
+* Generic collections MUST specify their element type.
+
+Incorrect:
+
+```java
+List items;
+```
+
+Correct:
+
+```java
+List<String> items;
+```
+
+* `Object` SHOULD NOT be used when a more specific type can express the contract.
+
+* Type casts SHOULD be minimized.
+
+---
+
+## 4. Optional
+
+* `Optional` MAY be used as a return type when absence is a meaningful result.
+
+Example:
+
+```java
+Optional<Booking> findBooking(BookingId id);
+```
+
+* `Optional` SHOULD NOT normally be used for:
+
+  * method parameters;
+  * entity fields;
+  * DTO fields;
+  * command fields;
+  * query fields.
+
+* `Optional` MUST NOT be used merely to avoid handling `null`.
+
+---
+
+## 5. Immutability
+
+* Immutable objects SHOULD be preferred where practical.
+
+* Mutable state MUST be minimized.
+
+* Fields that do not change after construction SHOULD be declared `final`.
+
+* Constructor-injected dependencies SHOULD be stored in `final` fields.
+
+* Static mutable state is forbidden unless explicitly justified and proven safe.
+
+* Public APIs SHOULD avoid exposing mutable internal collections.
+
+Prefer:
+
+```java
+public List<String> names() {
+    return List.copyOf(names);
+}
+```
+
+over exposing a mutable internal collection directly.
+
+---
+
+## 6. Java Records
+
+Java records SHOULD be used for immutable data carriers where appropriate.
+
+Suitable use cases include:
+
+* API request/response models;
+* commands;
+* queries;
+* immutable results;
+* simple value objects;
+* configuration data.
+
+Records SHOULD NOT be used when the object requires substantial mutable state or lifecycle behavior.
+
+---
+
+## 7. Collections
+
+* Use the most appropriate collection type for the required behavior.
+
+Examples:
+
+```text
+List      → ordered collection
+Set       → unique elements
+Map       → key/value lookup
+Queue     → processing order
+```
+
+* Do not expose mutable internal collections unnecessarily.
+
+* Prefer immutable collection factories when mutation is not required:
+
+```java
+List.of(...)
+Set.of(...)
+Map.of(...)
+```
+
+* Avoid unnecessary conversions between collection types.
+
+* Collection operations SHOULD remain readable rather than using unnecessarily complex streams.
+
+---
+
+## 8. Strings
+
+* Use `String` for textual data.
+
+* Avoid unnecessary string concatenation in loops.
+
+* Use `StringBuilder` when repeated mutable string construction is required.
+
+* Use text blocks for large multiline string literals where they improve readability.
+
+* String comparisons MUST use value comparison:
+
+```java
+if ("ACTIVE".equals(status)) {
+    ...
+}
+```
+
+or:
+
+```java
+if (status.equals("ACTIVE")) {
+    ...
+}
+```
+
+when nullability is guaranteed.
+
+Do not use:
+
+```java
+status == "ACTIVE"
+```
+
+for string value comparison.
+
+---
+
+## 9. Null Handling
+
+* Nullability MUST be intentional.
+
+* Methods SHOULD avoid returning `null` when a meaningful empty representation exists.
+
+Examples:
+
+```text
+Optional<T>
+empty collection
+empty result
+```
+
+* `null` MUST NOT be silently propagated through multiple layers.
+
+* Null checks SHOULD occur at the appropriate boundary.
+
+* `Objects.requireNonNull()` MAY be used when null is an invalid programmer input.
+
+---
+
+## 10. Exception Handling
+
+* Exceptions MUST represent meaningful failure conditions.
+
+* Exceptions MUST NOT be used for normal control flow.
+
+* Catch blocks MUST NOT silently swallow exceptions.
+
+Incorrect:
+
+```java
+try {
+    process();
+} catch (Exception ignored) {
+}
+```
+
+* Exceptions MUST be handled, translated, rethrown, or propagated appropriately.
+
+* When wrapping an exception, the original cause MUST be preserved.
+
+Example:
+
+```java
+throw new ProcessingException("Unable to process booking", cause);
+```
+
+* Catch the most specific exception type that can be handled.
+
+Avoid unnecessarily broad catches such as:
+
+```java
+catch (Exception e)
+```
+
+unless centralized error handling genuinely requires it.
+
+* Error messages MUST NOT contain secrets, credentials, tokens, or sensitive information.
+
+---
+
+## 11. Resource Management
+
+Resources that implement `AutoCloseable` MUST normally use try-with-resources.
+
+Preferred:
+
+```java
+try (InputStream input = resource.getInputStream()) {
+    // ...
+}
+```
+
+Avoid manually managing resource closure when try-with-resources is applicable.
+
+Resources such as:
+
+* streams;
+* readers;
+* writers;
+* JDBC resources;
+* files;
+
+MUST be closed appropriately.
+
+---
+
+## 12. Date and Time
+
+* Use the `java.time` API for new development.
+
+Preferred types include:
+
+```text
+Instant
+LocalDate
+LocalDateTime
+OffsetDateTime
+ZonedDateTime
+Duration
+Period
+```
+
+* Avoid legacy date/time APIs such as:
+
+```text
+java.util.Date
+java.util.Calendar
+```
+
+for new code unless required for interoperability.
+
+* The correct temporal type MUST be selected according to the meaning of the value.
+
+Examples:
+
+```text
+LocalDate       → date without time
+Instant         → point in time
+Duration        → elapsed time
+Period          → calendar-based amount
+```
+
+* Time-zone assumptions MUST be explicit where relevant.
+
+---
+
+## 13. Equality and Hashing
+
+Classes that define value-based equality MUST implement `equals()` and `hashCode()` consistently.
+
+The following contract MUST be preserved:
+
+```text
+a.equals(b) == true
+        ↓
+a.hashCode() == b.hashCode()
+```
+
+* `equals()` MUST be reflexive, symmetric, transitive, consistent, and false for `null`.
+
+* Mutable fields that participate in `hashCode()` SHOULD be avoided.
+
+* Java records SHOULD be preferred for simple immutable value-based data where appropriate.
+
+---
+
+## 14. Enums
+
+* Enums SHOULD be used when a value has a fixed, known set of states.
+
+Example:
+
+```java
+public enum BookingStatus {
+    CREATED,
+    CONFIRMED,
+    CANCELLED
+}
+```
+
+* Do not use arbitrary strings when an enum provides a stable domain-independent representation.
+
+* Enum names MUST use `UPPER_SNAKE_CASE`.
+
+* Business behavior MAY be placed in an enum when it is cohesive and improves clarity.
+
+---
+
+## 15. Switch Expressions
+
+Modern Java language features SHOULD be used when they improve clarity.
+
+Prefer switch expressions where appropriate:
+
+```java
+String description = switch (status) {
+    case CREATED -> "Booking created";
+    case CONFIRMED -> "Booking confirmed";
+    case CANCELLED -> "Booking cancelled";
+};
+```
+
+Avoid unnecessary legacy switch patterns when the modern syntax provides clearer behavior.
+
+---
+
+## 16. Streams and Lambdas
+
+Streams SHOULD be used when they improve readability and express collection transformations clearly.
+
+Example:
+
+```java
+List<String> names = bookings.stream()
+        .map(Booking::customerName)
+        .toList();
+```
+
+Streams SHOULD NOT be used when a simple loop is clearer.
+
+Avoid:
+
+* deeply nested stream pipelines;
+* side effects inside stream operations;
+* difficult-to-debug functional chains;
+* unnecessary stream creation.
+
+Stream operations SHOULD preferably remain side-effect free.
+
+---
+
+## 17. Method Design
+
+Methods SHOULD:
+
+* have one clear responsibility;
+* use meaningful names;
+* have a small and understandable parameter list;
+* avoid unnecessary side effects;
+* return meaningful results.
+
+Methods with many parameters SHOULD be reviewed for a clearer parameter object when appropriate.
+
+Methods MUST NOT be artificially split into numerous trivial methods merely to reduce line count.
+
+---
+
+## 18. Class Design
+
+Classes SHOULD have a clear responsibility.
+
+Classes SHOULD NOT become large collections of unrelated functionality.
+
+Avoid classes that:
+
+* contain unrelated utility methods;
+* maintain excessive mutable state;
+* expose unnecessary internal state;
+* perform unrelated operations.
+
+Inheritance SHOULD be used only when a genuine substitutable relationship exists.
+
+Composition SHOULD generally be preferred over inheritance when it provides clearer design.
+
+---
+
+## 19. Visibility
+
+* Use the narrowest visibility required.
+
+* Fields SHOULD generally be `private`.
+
+* Avoid unnecessary `public` methods and classes.
+
+* Package-private visibility MAY be used when functionality is intended only for the package.
+
+* Public APIs SHOULD expose only what consumers actually require.
+
+---
+
+## 20. Static State
+
+* Static constants are allowed.
+
+Example:
+
+```java
+private static final String DEFAULT_STATUS = "ACTIVE";
+```
+
+* Static mutable state is forbidden unless explicitly justified.
+
+* Static service locators are forbidden.
+
+* Global mutable caches MUST have an explicit lifecycle and concurrency strategy.
+
+---
+
+## 21. Reflection
+
+* Reflection MUST NOT be used for normal application logic unless there is a genuine requirement.
+
+* Framework-required reflection MAY be used.
+
+* New reflection-based infrastructure MUST have an explicit justification.
+
+* Reflection MUST NOT be introduced merely to avoid writing straightforward Java code.
+
+---
+
+## 22. Concurrency
+
+* Shared mutable state SHOULD be avoided.
+
+* Concurrent code MUST have an explicit thread-safety strategy.
+
+* Blocking operations MUST NOT be performed on event-loop or reactive threads.
+
+* Threads MUST NOT be created manually without an explicit lifecycle and ownership strategy.
+
+* Executors SHOULD be managed by the application's configured execution infrastructure.
+
+* When asynchronous processing is used, the following SHOULD be considered explicitly:
+
+  * timeout;
+  * cancellation;
+  * exception handling;
+  * resource limits;
+  * thread safety;
+  * context propagation.
+
+---
+
+## 23. Virtual Threads
+
+Virtual threads MAY be used when appropriate for blocking I/O workloads.
+
+They MUST NOT be introduced automatically.
+
+Before using virtual threads, the application SHOULD consider:
+
+* blocking dependencies;
+* database connection pool limits;
+* external service limits;
+* thread-local usage;
+* context propagation;
+* observability.
+
+The use of virtual threads MUST remain consistent with the project's runtime configuration.
+
+---
+
+## 24. Logging
+
+Logging MUST follow the application's logging standards.
+
+Production code MUST NOT log:
+
+* passwords;
+* credentials;
+* access tokens;
+* refresh tokens;
+* API keys;
+* secrets;
+* payment card information;
+* sensitive personal information.
+
+Logs SHOULD contain useful diagnostic context without exposing sensitive data.
+
+Logging MUST NOT replace proper exception handling.
+
+---
+
+## 25. Time and Randomness
+
+Code that depends on current time or randomness SHOULD remain testable.
+
+Direct use of:
+
+```java
+Instant.now()
+UUID.randomUUID()
+```
+
+is permitted when appropriate.
+
+Where deterministic testing requires control over time or randomness, an appropriate abstraction MAY be introduced.
+
+Abstractions MUST NOT be introduced merely because they are theoretically possible.
+
+---
+
+## 26. Comments
+
+Comments SHOULD explain intent where the code cannot reasonably express it.
+
+Comments SHOULD NOT:
+
+* restate obvious code;
+* describe syntax;
+* contain outdated implementation details;
+* replace meaningful naming.
+
+Commented-out production code MUST be removed before merge.
+
+TODO comments SHOULD identify a genuine follow-up requirement and MUST NOT be used as a substitute for completing required work.
+
+---
+
+## 27. Documentation
+
+Public APIs SHOULD be documented where their behavior is not self-explanatory.
+
+Non-obvious implementation decisions MAY be documented.
+
+Documentation SHOULD remain concise and accurate.
+
+Documentation MUST be updated when public behavior changes.
+
+---
+
+## 28. Formatting
+
+Code MUST follow the project's configured Java formatter.
+
+Where no project-specific formatter exists, the team SHOULD adopt a single automated formatter.
+
+Formatting MUST be automated where practical.
+
+Developers SHOULD NOT spend review time debating formatting that can be enforced automatically.
+
+---
+
+## 29. Static Analysis
+
+Static analysis SHOULD be enabled for production projects.
+
+Where configured:
+
+* compiler warnings SHOULD be treated seriously;
+* unused imports MUST be removed;
+* unreachable code MUST be removed;
+* unsafe casts SHOULD be eliminated;
+* obvious nullability issues SHOULD be addressed;
+* code-quality violations MUST be resolved or explicitly justified.
+
+The project's configured static-analysis tools are authoritative.
+
+---
+
+## 30. Dependencies
+
+New dependencies MUST comply with the project's dependency policy.
+
+Existing approved dependencies SHOULD be reused when they already provide the required capability.
+
+New libraries MUST NOT be introduced merely for convenience when the Java standard library or an existing project dependency provides an adequate solution.
+
+Unused dependencies MUST be removed.
+
+Dependency selection MUST consider:
+
+* maintenance;
+* security;
+* licensing;
+* compatibility;
+* project support;
+* operational impact.
+
+See:
+
+```text
+dependency-policy.md
+```
+
+---
+
+## 31. Testing
+
+Production code MUST be testable.
+
+Tests SHOULD:
+
+* be deterministic;
+* be isolated;
+* have clear names;
+* test observable behavior;
+* avoid unnecessary implementation coupling.
+
+Unit tests SHOULD execute quickly and independently.
+
+Integration tests SHOULD be used where behavior depends on:
+
+* databases;
+* frameworks;
+* external services;
+* messaging;
+* infrastructure.
+
+Tests MUST NOT depend on production infrastructure.
+
+---
+
+## 32. Forbidden Coding Patterns
+
+The following are forbidden unless explicitly justified and approved:
+
+1. Raw generic types.
+
+2. Silent exception swallowing.
+
+3. Hard-coded credentials, secrets, tokens, or API keys.
+
+4. Logging secrets or protected sensitive data.
+
+5. Unmanaged thread creation.
+
+6. Unnecessary static mutable state.
+
+7. Reflection for ordinary business/application logic.
+
+8. `==` for String value comparison.
+
+9. Legacy date/time APIs for new functionality without an interoperability requirement.
+
+10. Commented-out production code.
+
+11. Dead or unreachable production code.
+
+12. Unused dependencies.
+
+13. Catching broad exceptions when a specific exception can be handled.
+
+14. Using exceptions as normal control flow.
+
+15. Excessively complex stream pipelines when a simple loop is clearer.
+
+16. Speculative abstractions introduced without a concrete requirement.
+
+17. Duplicate utility implementations when an existing standard library or approved dependency already provides the required functionality.
+
+---
+
+## 33. Quality Gates
+
+The project MUST comply with the quality gates defined by its active build and CI configuration.
+
+Where configured:
+
+* compilation MUST succeed;
+* automated tests MUST pass;
+* formatting checks MUST pass;
+* static analysis MUST pass;
+* dependency checks MUST pass;
+* license checks MUST pass;
+* security scanning MUST pass;
+* configured code-quality thresholds MUST be satisfied.
+
+The exact commands and tools MUST come from the project's build configuration.
+
+This document does NOT mandate a specific build tool, database, testing framework, static-analysis tool, or CI platform.
+
+---
+
+## 34. Related Standards
+
+See also:
+
+* `dependency-policy.md`
+* `ai-rules.md`
+
+```
+
+This version is intentionally **technology/coding focused only**. Architecture rules such as:
+
+- `adapter/application/domain/infrastructure`
+- Hexagonal Architecture
+- Modular Monolith
+- controller → use case
+- persistence boundaries
+- module boundaries
+
+belong in `clean-architecture.md`, not here.
+```