What is PECS and why is it important?

PECS stands for Producer Extends Consumer Super; it guides wildcard usage to preserve type safety for producers and consumers.

When should I avoid the diamond operator?

Use the diamond operator when the compiler can infer the type. Avoid it if inference is ambiguous or you're targeting very old Java versions.

How do I handle type erasure in generics?

Type erasure removes generic type parameters at runtime; use type tokens, TypeReference/TypeToken, factories, and well-designed APIs to preserve type information where needed.

128-java-generics

npx machina-cli add skill jabrena/cursor-rules-java/128-java-generics --openclaw

Files (1)

SKILL.md

2.9 KB

Java Generics Best Practices

Review and improve Java code using comprehensive generics best practices that enforce compile-time type safety and enable flexible, reusable APIs.

Core areas: Type safety (avoiding raw types, eliminating unsafe casts), code reusability (generic methods and types for multiple type contexts), API clarity (PECS wildcards — ? extends for producers, ? super for consumers), performance optimization (eliminating boxing/casting overhead), diamond operator for type inference, type erasure awareness (type tokens, factory patterns, array creation), generic inheritance and variance (invariance, covariance, contravariance), @SafeVarargs for heap pollution prevention, wildcard capture helpers, self-bounded generics (CRTP) for fluent builders, proper wildcard API design with Comparator<? super T> and Function<? super T, ? extends R>, arrays-vs-generics covariance pitfalls, serialization with TypeReference/TypeToken, eliminating unchecked warnings, generic naming conventions (T, E, K/V, ?), typesafe heterogeneous containers, and integration with Records, sealed types, and pattern matching.

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 generics issues categorized by impact (CRITICAL, MAINTAINABILITY, PERFORMANCE, TYPE_SAFETY) and area (raw types, wildcard misuse, bounded parameter opportunities, type erasure problems, modern feature integration gaps). Step 3 eliminates raw types and unsafe casts with proper parameterization. Step 4 applies PECS wildcards and bounded type parameters for flexible APIs. Step 5 introduces diamond operator, generic methods, and type tokens for type erasure scenarios. Step 6 integrates generics with Records, sealed types, and pattern matching. 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/128-java-generics.md.

Source

git clone https://github.com/jabrena/cursor-rules-java/blob/main/skills/128-java-generics/SKILL.mdView on GitHub

Overview

Java Generics Best Practices guide you to review and refactor code for type safety and reusable APIs. It covers avoiding raw types, applying PECS wildcards, bounded type parameters, and leveraging modern features such as Records, sealed types, and pattern matching, while addressing type erasure and safe varargs.

How This Skill Works

Step 1 ensures the project compiles cleanly. Step 2 analyzes generics issues by impact and area (TYPE_SAFETY, MAINTAINABILITY, PERFORMANCE). Step 3 refactors to remove raw types, applies PECS, adds bounded parameters, introduces diamond operator and type-safe generics, and aligns with modern features.

When to Use It

When auditing a codebase for raw types, unsafe casts, or unchecked warnings.
When designing reusable APIs that should work across multiple types using PECS wildcards.
When implementing generic algorithms and methods with bounded type parameters.
When integrating generics with Records, sealed types, and pattern matching.
When optimizing for performance by avoiding boxing and unnecessary casts.

Quick Start

Step 1: Run mvnw compile to validate the project.
Step 2: Identify raw types and unsafe casts in the codebase.
Step 3: Apply PECS, bounded generics, and diamond operator changes, then run mvn test/verify.

Best Practices

Avoid raw types and unchecked casts by parameterizing collections and APIs.
Apply PECS: use ? extends for producers and ? super for consumers.
Use bounded type parameters to constrain generics and improve readability.
Prefer the diamond operator and consider type tokens for type-erasure scenarios.
Use safe varargs (@SafeVarargs) and well-designed wildcard APIs (e.g., Comparator<? super T>).

Example Use Cases

Replace raw List usage with List<T> and remove unsafe casts.
Design a generic API using PECS in a producer-consumer scenario.
Implement a bounded generic method with <T extends Number> to summarize numeric values.
Refactor factory methods to use the diamond operator for clearer inference.
Introduce TypeToken/TypeReference to preserve generic type info at runtime.

Frequently Asked Questions

Add this skill to your agents