AgentSkillsCN

effective-java-core

在编写或审查 Java 代码时，遵循《Effective Java》（第二版）的最佳实践：对象的创建与生命周期、对象相等性、类的设计、泛型、枚举与注解、方法设计、通用编程、异常处理，以及序列化（不包括并发相关内容）。

SKILL.md
--- frontmatter
name: effective-java-core
description: "Apply Effective Java (2nd edition) best practices when writing or reviewing Java code: object creation/lifecycle, equality, class design, generics, enums/annotations, methods, general programming, exceptions, and serialization (excludes concurrency)."

Effective Java Core (2nd ed)

Guideline checklist derived from docs/effective_java.md (Bloch, Effective Java 2nd edition). If another repo skill sets stricter rules, follow the stricter one.

Use effective-java-concurrency for concurrency-specific guidance (Items 66-73).

Quick workflow

  1. •Identify the API surface (public/protected). Minimize it and document contracts.
  2. •Prefer immutability and defensive copies; avoid exposing mutable internals.
  3. •Choose the right construction pattern (static factory / builder / singleton) and lifetime rules.
  4. •Make object methods correct (equals/hashCode/toString/Comparable); avoid clone.
  5. •Use generics, enums, and exceptions intentionally; avoid cleverness unless measured.
  6. •Treat serialization as exported API; avoid it unless you truly need it.

Checklist by item

Creating and destroying objects (1-7)

  • •1: Prefer static factories when naming, instance control/caching, or subtype returns help.
  • •2: Use builders when constructors/static factories would have many params; avoid telescoping.
  • •3: Enforce singleton with enum (preferred) or private constructor + static field/factory.
  • •4: Enforce noninstantiability for utility classes with a private constructor.
  • •5: Avoid creating unnecessary objects (reuse immutables; cache expensive objects; avoid boxing).
  • •6: Eliminate obsolete references (null out unused refs; watch caches/listeners/ThreadLocals).
  • •7: Avoid finalizers; prefer AutoCloseable + try-with-resources for cleanup.

Methods common to all objects (8-12)

  • •8: equals must be reflexive, symmetric, transitive, consistent, and return false for null.
  • •9: If overriding equals, always override hashCode (equal objects -> equal hash codes).
  • •10: Override toString for value-ish types; include key state; document format if relied upon.
  • •11: Avoid clone; prefer copy constructor/factory. If implementing, obey the contract.
  • •12: Implement Comparable when a natural order exists; avoid subtraction in comparisons.

Classes and interfaces (13-22)

  • •13: Minimize accessibility of classes/members; expose the smallest surface that works.
  • •14: In public classes, use accessors; do not expose mutable public fields.
  • •15: Minimize mutability; make classes/fields final where possible; prevent representation leaks.
  • •16: Favor composition over inheritance; use inheritance only for true "is-a" relationships.
  • •17: Design and document for inheritance, or else prohibit it (e.g., make the class final).
  • •18: Prefer interfaces to abstract classes; keep implementations swappable.
  • •19: Use interfaces to define types; do not use "constant interfaces".
  • •20: Prefer class hierarchies to tagged classes; leverage polymorphism.
  • •21: Use function objects to represent strategies (pass behavior rather than branch on tags).
  • •22: Favor static member classes over nonstatic to avoid implicit outer references.

Generics (23-29)

  • •23: Do not use raw types; always parameterize generic types.
  • •24: Eliminate unchecked warnings; keep any @SuppressWarnings("unchecked") local and justified.
  • •25: Prefer lists to arrays (arrays are covariant/reified; generics are invariant/erased).
  • •26: Favor generic types for reusable components.
  • •27: Favor generic methods for reusable algorithms.
  • •28: Use bounded wildcards to increase flexibility (PECS: producer extends, consumer super).
  • •29: Consider type-safe heterogeneous containers for keyed type->value storage patterns.

Enums and annotations (30-37)

  • •30: Use enums instead of int constants.
  • •31: Use instance fields instead of ordinals; never persist/communicate ordinal().
  • •32: Use EnumSet instead of bit fields.
  • •33: Use EnumMap instead of ordinal indexing.
  • •34: Emulate extensible enums with interfaces (when clients must supply their own "enum" values).
  • •35: Prefer annotations to naming patterns.
  • •36: Use @Override consistently.
  • •37: Prefer marker interfaces over marker annotations when you want a true "type" signal.

Methods (38-44)

  • •38: Validate parameters; document constraints; fail fast with the right exception.
  • •39: Make defensive copies when needed (especially of mutable inputs/outputs).
  • •40: Design signatures carefully (clarity > brevity; avoid long param lists; prefer enums).
  • •41: Use overloading judiciously; prefer distinct method names when overloads can confuse.
  • •42: Use varargs judiciously; avoid varargs in performance-critical paths.
  • •43: Return empty arrays/collections, not nulls.
  • •44: Write doc comments for every exposed API element; describe contracts and edge cases.

General programming (45-56)

  • •45: Minimize scope of local variables; initialize at declaration where possible.
  • •46: Prefer for-each loops to indexed loops unless you need indices or mutation by index.
  • •47: Know and use libraries; do not re-invent standard utilities.
  • •48: Avoid float/double for exact values; use BigDecimal, int, or long.
  • •49: Prefer primitives to boxed primitives; avoid accidental boxing and NullPointerExceptions.
  • •50: Avoid strings when other types are more appropriate (use proper types for IDs, money, etc.).
  • •51: Beware string concatenation performance in loops; use StringBuilder.
  • •52: Refer to objects by their interface type.
  • •53: Prefer interfaces to reflection; avoid reflective access in normal code paths.
  • •54: Use native methods judiciously; avoid unless you need platform-specific features/perf.
  • •55: Optimize judiciously (measure; design for performance without premature micro-optimizations).
  • •56: Adhere to generally accepted naming conventions for readability and consistency.

Exceptions (57-65)

  • •57: Use exceptions only for exceptional conditions; do not use them for control flow.
  • •58: Use checked exceptions for recoverable conditions; runtime exceptions for programming errors.
  • •59: Avoid unnecessary checked exceptions; prefer returning optional results where appropriate.
  • •60: Favor standard exceptions (e.g., IllegalArgumentException, IllegalStateException).
  • •61: Throw exceptions appropriate to the abstraction; do not leak lower-level details.
  • •62: Document all exceptions thrown by each method (especially in public APIs).
  • •63: Include failure-capture information in detail messages for debugging.
  • •64: Strive for failure atomicity (on failure, leave objects unchanged or in a valid state).
  • •65: Do not ignore exceptions; handle, propagate, or explicitly justify suppression.

Serialization (74-78)

  • •74: Implement Serializable judiciously; it becomes part of your exported API.
  • •75: Consider a custom serialized form; declare serialVersionUID; mark derived fields transient.
  • •76: Write readObject defensively (defensive copies + invariant checks); avoid overridable calls.
  • •77: For instance control, prefer enum singletons to readResolve; beware readResolve attacks.
  • •78: Prefer serialization proxies when you must serialize complex invariants.

Getting the full details quickly

Prefer opening the smallest relevant reference file (same original structure + code blocks):

  • •Items 1-7: .codex/skills/effective-java-core/references/02-creating-and-destroying-objects.md
  • •Items 8-12: .codex/skills/effective-java-core/references/03-methods-common-to-all-objects.md
  • •Items 13-22: .codex/skills/effective-java-core/references/04-classes-and-interfaces.md
  • •Items 23-29: .codex/skills/effective-java-core/references/05-generics.md
  • •Items 30-37: .codex/skills/effective-java-core/references/06-enums-and-annotations.md
  • •Items 38-44: .codex/skills/effective-java-core/references/07-methods.md
  • •Items 45-56: .codex/skills/effective-java-core/references/08-general-programming.md
  • •Items 57-65: .codex/skills/effective-java-core/references/09-exceptions.md
  • •Items 74-78: .codex/skills/effective-java-core/references/11-serialization.md

For navigation:

  • •Table of contents: .codex/skills/effective-java-core/references/01-table-of-contents.md

Legacy (large, avoid loading unless you truly need everything at once):

  • •.codex/skills/effective-java-core/references/effective_java.md

You can also search the repo source summary:

  • •File: docs/effective_java.md
  • •Find a specific item: rg -n '^## 12\\.' docs/effective_java.md