122-java-type-design
npx machina-cli add skill jabrena/cursor-rules-java/122-java-type-design --openclawType Design Thinking in Java
Review and improve Java code using comprehensive type design principles that apply typography concepts to code structure and organization for maximum clarity and maintainability.
Core areas: Clear type hierarchies (nested static classes, logical structure), consistent naming conventions (domain-driven patterns, uniform interface/implementation naming), strategic whitespace for readability, type-safe wrappers (value objects replacing primitive obsession, EmailAddress, Money), generic type parameters (flexible reusable types, bounded parameters), domain-specific fluent interfaces (builder pattern, method chaining), type "weights" (conceptual importance assignment — core domain vs supporting vs utility), type contrast through interfaces (contract vs implementation separation), aligned method signatures (consistent parameter and return types across related classes), self-documenting code (clear descriptive names), BigDecimal for precision-sensitive calculations (financial/monetary operations), and strategic type selection (Optional, Set vs List, interfaces over concrete types).
Prerequisites: Run ./mvnw compile or mvn compile before applying any change. If compilation fails, stop immediately and do not proceed — compilation failure is a blocking condition.
Multi-step scope: Step 1 validates the project compiles. Step 2 analyzes Java code to identify type design issues categorized by impact (CRITICAL, MAINTAINABILITY, TYPE_SAFETY, READABILITY) and area (naming conventions, type hierarchies, generic usage, primitive obsession, type safety, precision). Step 3 applies naming convention improvements and type hierarchy restructuring. Step 4 eliminates primitive obsession by creating domain-specific value objects and records. Step 5 introduces proper generic type parameters with appropriate bounds and type-safe wrappers. Step 6 implements precision-appropriate numeric types and strategic collection/type selection. Step 7 validates all changes compile and all tests pass with ./mvnw clean verify.
Before applying changes: Read the reference for detailed examples, good/bad patterns, and constraints.
Reference
For detailed guidance, examples, and constraints, see references/122-java-type-design.md.
Source
git clone https://github.com/jabrena/cursor-rules-java/blob/main/skills/122-java-type-design/SKILL.mdView on GitHub Overview
This skill guides reviewing, improving, and refactoring Java code to enhance type design quality. It covers clear type hierarchies, consistent naming, eliminating primitive obsession with domain-specific value objects, generics, type-safe wrappers, fluent interfaces, and precise numeric types like BigDecimal for finance. It’s part of the skills-for-java project.
How This Skill Works
You run through steps: verify the project compiles, analyze type design issues by impact and area, then apply targeted changes to naming, hierarchies, wrappers, generics, and precision handling. The approach emphasizes domain-specific value objects, type-safe wrappers, fluent interfaces, aligned method signatures, and using BigDecimal for precision-sensitive calculations.
When to Use It
- Review a codebase for clear type hierarchies and consistent naming to improve readability and maintainability
- Eliminate primitive obsession by introducing domain-specific value objects like EmailAddress or Money
- Introduce generic type parameters with sensible bounds to create reusable, type-safe APIs
- Design domain-specific fluent interfaces and builders with coherent method chaining
- Adopt precision-appropriate numeric types (BigDecimal) and choose appropriate collection types (Optional, Set vs List) for accuracy
Quick Start
- Step 1: Run ./mvnw compile to ensure the project builds cleanly
- Step 2: Identify primitive-obsessed areas and introduce domain value objects (EmailAddress, Money) and wrappers
- Step 3: Introduce generics, domain-specific fluent interfaces, and BigDecimal usage; run ./mvnw clean verify
Best Practices
- Map domain concepts to explicit types and minimize primitive scattering across the codebase
- Use value objects for business rules (e.g., Money, EmailAddress) instead of raw primitives
- Prefer interfaces over concrete implementations to improve type contrast and testability
- Keep related method signatures aligned across classes to improve readability and predictability
- Choose BigDecimal for monetary calculations and select the right collection semantics
Example Use Cases
- EmailAddress as a value object with validation and normalization logic
- Money type wrapping BigDecimal with currency metadata
- Fluent builder for domain entities using a typed, chainable API
- Generic Wrapper<T> with bounded type parameters for reusable containers
- Interface-driven design with IPayment and concrete implementations
