@booklib/core 2.0.0

package/skills/effective-java/references/review-checklist.md

@@ -0,0 +1,216 @@
+# Effective Java Code Review Checklist
+
+Use this checklist when reviewing Java code. Work through each section and flag any
+violations. Not every section applies to every review — skip sections that aren't
+relevant to the code under review.
+
+---
+
+## 1. Object Creation
+
+- [ ] Static factory methods used where beneficial (named construction, caching, return subtypes)
+- [ ] Builder pattern used for classes with many optional parameters
+- [ ] Singleton enforcement is correct (enum type or private constructor with static field)
+- [ ] Utility classes have private constructor to prevent instantiation
+- [ ] Dependencies are injected, not hardwired to concrete implementations
+- [ ] No unnecessary object creation (cached patterns, primitive vs boxed in loops)
+- [ ] Obsolete object references are nulled out (custom collections, caches, listeners)
+- [ ] try-with-resources used for all AutoCloseable objects
+- [ ] No finalizers or cleaners (except as safety nets for native resources)
+
+**Red flags**: Telescoping constructors with 4+ parameters. `new String("literal")`.
+`Long sum = 0L` in a loop. Resources closed in finally blocks instead of
+try-with-resources. Finalizer or cleaner used for non-native resource cleanup.
+
+---
+
+## 2. Methods Common to All Objects
+
+- [ ] `equals` override obeys the contract (reflexive, symmetric, transitive, consistent)
+- [ ] `hashCode` is overridden whenever `equals` is overridden
+- [ ] `toString` provides useful diagnostic information
+- [ ] `clone` is avoided in favor of copy constructors or copy factories
+- [ ] `Comparable` is implemented where natural ordering exists
+- [ ] Comparators don't use subtraction (overflow risk)
+
+**Red flags**: `equals` that breaks symmetry (subclass vs superclass). Missing `hashCode`
+override causing HashMap failures. `Cloneable` implemented on new classes. Comparator
+using `return o1.val - o2.val` (integer overflow).
+
+---
+
+## 3. Class Design
+
+- [ ] Classes and members have minimal accessibility (private > package-private > protected > public)
+- [ ] Instance fields are never public (use accessors)
+- [ ] Classes are immutable where possible (final fields, no setters, final class or private constructor)
+- [ ] Composition is used instead of inheritance across package boundaries
+- [ ] Classes designed for inheritance document self-use of overridable methods
+- [ ] Classes not designed for inheritance are final or have private constructors
+- [ ] Interfaces are used to define types, not for constants
+- [ ] Tagged classes are refactored into class hierarchies
+- [ ] Inner classes are static unless they need an enclosing instance reference
+- [ ] One top-level class per source file
+
+**Red flags**: Public mutable fields. Concrete class extended across package boundary
+without documentation of overridable method self-use. Non-static inner class in a
+long-lived object (hidden reference causes memory leak). Constant interface
+(`interface Constants { int FOO = 1; }`).
+
+---
+
+## 4. Generics
+
+- [ ] No raw types anywhere in the codebase
+- [ ] All unchecked warnings are eliminated or suppressed with justification
+- [ ] Lists preferred over arrays for generic collections
+- [ ] Types and methods are generic where appropriate
+- [ ] Bounded wildcards used per PECS (Producer-Extends, Consumer-Super)
+- [ ] `@SafeVarargs` used correctly on generic varargs methods
+- [ ] No wildcards on return types
+
+**Red flags**: `List` instead of `List<String>`. `@SuppressWarnings("unchecked")` on a
+large scope without comment. `E[]` used where `List<E>` would be safer. Missing
+wildcards on API parameters that accept subtypes.
+
+---
+
+## 5. Enums and Annotations
+
+- [ ] Enums used instead of `int` or `String` constants
+- [ ] Enum values don't derive from `ordinal()` — instance fields used instead
+- [ ] `EnumSet` used instead of bit fields
+- [ ] `EnumMap` used instead of ordinal-indexed arrays
+- [ ] `@Override` annotation present on all overriding methods
+- [ ] Annotations used instead of naming patterns
+
+**Red flags**: `public static final int SEASON_WINTER = 0`. Calling `ordinal()` to
+derive a value. `int` flags combined with bitwise OR instead of `EnumSet`. Array
+indexed by `enum.ordinal()`.
+
+---
+
+## 6. Lambdas and Streams
+
+- [ ] Lambdas used instead of anonymous classes for functional interfaces
+- [ ] Method references used where clearer than lambdas
+- [ ] Standard functional interfaces from `java.util.function` used before custom ones
+- [ ] Streams used judiciously (not forced where loops are clearer)
+- [ ] Stream operations are side-effect-free (no mutation in `forEach` used for computation)
+- [ ] `Collection` returned from APIs instead of `Stream`
+- [ ] Parallel streams used only with appropriate data structures and verified speedup
+
+**Red flags**: Long, complex lambdas (should be extracted to methods). `forEach` used
+for computation instead of collect/reduce. `Stream.parallel()` on `LinkedList` or
+`Stream.iterate`. Stream pipeline with side effects on shared mutable state.
+
+---
+
+## 7. Method Design
+
+- [ ] Parameters validated at method entry (`Objects.requireNonNull`, bounds checks)
+- [ ] Defensive copies made of mutable input parameters (copy before validation)
+- [ ] Method signatures have ≤4 parameters (or use helper classes / Builder)
+- [ ] No confusing overloads (same number of parameters with different behavior)
+- [ ] Varargs methods require at least one argument where needed
+- [ ] Empty collections/arrays returned instead of null
+- [ ] `Optional` used appropriately for absent return values (not for fields/parameters/collections)
+- [ ] All exported API elements have doc comments
+
+**Red flags**: Missing null check that leads to NPE deep in call stack. Mutable
+`Date`/`Calendar` parameter stored directly without copy. Method returning `null`
+instead of `Collections.emptyList()`. `Optional.get()` without presence check.
+Overloaded methods with same arity causing dispatch surprises.
+
+---
+
+## 8. General Programming
+
+- [ ] Local variables declared at point of first use with minimal scope
+- [ ] For-each loops used wherever applicable
+- [ ] Standard library methods used instead of hand-rolled equivalents
+- [ ] `BigDecimal` or `int`/`long` used for monetary calculations (not `float`/`double`)
+- [ ] Primitive types preferred over boxed primitives
+- [ ] Strings not used as substitutes for other types (enums, aggregates, capabilities)
+- [ ] `StringBuilder` used for string concatenation in loops
+- [ ] Objects referred to by interface types where appropriate
+- [ ] Reflection avoided except for class instantiation via interfaces
+- [ ] Naming conventions followed (camelCase methods, UPPER_SNAKE constants, etc.)
+
+**Red flags**: `double` used for currency. `String` concatenation with `+` inside a loop
+building large output. `==` applied to boxed primitives. Hand-rolled sorting or data
+structure instead of using `java.util` classes. Variable declared far from use with
+wide scope.
+
+---
+
+## 9. Exceptions
+
+- [ ] Exceptions used only for exceptional conditions (not control flow)
+- [ ] Checked exceptions for recoverable conditions, runtime for programming errors
+- [ ] Unnecessary checked exceptions eliminated (consider Optional or method splitting)
+- [ ] Standard exceptions reused (`IllegalArgumentException`, `NullPointerException`, etc.)
+- [ ] Exceptions translated at abstraction boundaries (with chaining)
+- [ ] All exceptions documented with `@throws`
+- [ ] Exception detail messages include failure-capture information
+- [ ] Methods are failure-atomic (object state unchanged on failure)
+- [ ] No empty catch blocks (if intentionally ignored, document why and use `ignored` variable name)
+
+**Red flags**: `try { ... } catch (Exception e) { }` (swallowed exception). Exception
+used for flow control (`try { array[i++] } catch (AIOOBE)`). Method declares
+`throws Exception`. Low-level `SQLException` propagated through business logic instead
+of translated.
+
+---
+
+## 10. Concurrency
+
+- [ ] Shared mutable data is properly synchronized or volatile
+- [ ] Minimal work done inside synchronized regions
+- [ ] No alien method calls within synchronized blocks
+- [ ] `ExecutorService` used instead of raw `Thread` management
+- [ ] `java.util.concurrent` utilities preferred over `wait`/`notify`
+- [ ] Thread safety level documented on every class
+- [ ] Lazy initialization used only when necessary, with correct idiom
+- [ ] No dependence on thread scheduler behavior (`Thread.yield`, priorities)
+
+**Red flags**: Non-volatile field used as stop flag across threads. Long computation
+inside synchronized block. `wait()` without loop. `new Thread(runnable).start()` instead
+of executor. Missing thread safety documentation. Single-check idiom used where
+double-check is required.
+
+---
+
+## 11. Serialization
+
+- [ ] Java serialization avoided (JSON, protobuf, or other formats preferred)
+- [ ] If Serializable: considered impact on flexibility and security
+- [ ] If Serializable: custom serialized form used where default is inappropriate
+- [ ] If Serializable: `readObject` validates defensively like a constructor
+- [ ] If Serializable: enum types preferred for instance-controlled classes
+- [ ] If Serializable: serialization proxy pattern considered
+- [ ] No deserialization of untrusted data
+
+**Red flags**: `ObjectInputStream.readObject()` on untrusted input. Default serialized
+form exposing internal representation. `readObject` that doesn't validate or make
+defensive copies. Non-enum singleton implementing `Serializable` without `readResolve`
+or serialization proxy.
+
+---
+
+## Severity Classification
+
+When reporting issues, classify them:
+
+- **Critical**: Bug, security vulnerability, or data corruption risk
+  (e.g., missing synchronization on shared mutable data, deserializing untrusted data,
+  broken equals/hashCode contract, empty catch block hiding failures)
+- **Major**: Significant design debt or maintenance burden
+  (e.g., concrete class inheritance, raw types, mutable class that should be immutable,
+  telescoping constructors, checked exceptions that should be unchecked)
+- **Minor**: Best practice deviation with limited immediate impact
+  (e.g., missing @Override, toString not implemented, unnecessary object creation,
+  for-loop instead of for-each)
+- **Suggestion**: Improvement that would be nice but isn't urgent
+  (e.g., consider Builder for future extensibility, evaluate switching to Optional
+  return type, document thread safety level)

package/skills/effective-java/scripts/checkstyle_setup.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""
+checkstyle_setup.py - Set up Checkstyle with an Effective Java-aligned configuration.
+
+Usage:
+    python checkstyle_setup.py [--output-dir ./]
+
+Generates:
+    effective-java-checkstyle.xml  - Checkstyle rules mapped to Effective Java items
+    run_checkstyle.sh              - Shell script to run Checkstyle on src/
+
+Each config section references the Effective Java item it enforces.
+"""
+
+import argparse
+import os
+import pathlib
+import stat
+import sys
+import urllib.request
+import urllib.error
+
+CHECKSTYLE_VERSION = "10.14.2"
+CHECKSTYLE_JAR = f"checkstyle-{CHECKSTYLE_VERSION}-all.jar"
+CHECKSTYLE_URL = (
+    f"https://github.com/checkstyle/checkstyle/releases/download/"
+    f"checkstyle-{CHECKSTYLE_VERSION}/{CHECKSTYLE_JAR}"
+)
+
+CHECKSTYLE_XML = """\
+<?xml version="1.0"?>
+<!DOCTYPE module PUBLIC
+    "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
+    "https://checkstyle.org/dtds/configuration_1_3.dtd">
+
+<!--
+  Effective Java - Checkstyle Configuration
+  Each module references the Effective Java item it enforces.
+  Book: "Effective Java" by Joshua Bloch, 3rd Edition.
+-->
+<module name="Checker">
+  <property name="severity" value="warning"/>
+
+  <module name="TreeWalker">
+
+    <!--
+      Item 15: Minimize the accessibility of classes and members.
+      Prefer private fields; expose only what is necessary.
+    -->
+    <module name="VisibilityModifier">
+      <property name="protectedAllowed" value="false"/>
+      <property name="publicMemberPattern" value="^serialVersionUID$"/>
+    </module>
+
+    <!--
+      Item 17: Minimize mutability — utility/helper classes should be final.
+      FinalClass flags classes with only private constructors that are not final.
+    -->
+    <module name="FinalClass"/>
+
+    <!--
+      Item 10: Obey the general contract when overriding equals.
+      Always override hashCode when you override equals.
+    -->
+    <module name="EqualsHashCode"/>
+
+    <!--
+      Item 34: Use enums instead of int constants.
+      Magic numbers in code signal that an enum or named constant should be used.
+    -->
+    <module name="MagicNumber">
+      <property name="ignoreNumbers" value="-1, 0, 1, 2"/>
+      <property name="ignoreAnnotation" value="true"/>
+      <property name="ignoreHashCodeMethod" value="true"/>
+    </module>
+
+    <!--
+      Item 77: Don't ignore exceptions.
+      Empty catch blocks hide failures; always handle or rethrow.
+    -->
+    <module name="EmptyCatchBlock">
+      <property name="exceptionVariableName" value="expected|ignore"/>
+    </module>
+
+    <!--
+      Item 2: Consider a builder when faced with many constructor parameters.
+      More than 3 parameters is a signal to introduce a Builder.
+    -->
+    <module name="ParameterNumber">
+      <property name="max" value="3"/>
+      <property name="tokens" value="METHOD_DEF, CTOR_DEF"/>
+    </module>
+
+    <!--
+      General best practice aligned with Effective Java's emphasis on small,
+      focused methods. Methods longer than 30 lines are harder to reason about.
+    -->
+    <module name="MethodLength">
+      <property name="max" value="30"/>
+      <property name="countEmpty" value="false"/>
+    </module>
+
+    <!--
+      Item 11: Always override toString.
+      Not directly checkable, but HideUtilityClassConstructor complements
+      Item 4 (enforce non-instantiability with private constructor).
+    -->
+    <module name="HideUtilityClassConstructor"/>
+
+    <!--
+      Item 57: Minimize the scope of local variables.
+      Inner assignments make scope harder to reason about.
+    -->
+    <module name="InnerAssignment"/>
+
+    <!--
+      Item 67: Optimize judiciously — avoid redundant string concatenation in loops.
+    -->
+    <module name="StringLiteralEquality"/>
+
+  </module>
+</module>
+"""
+
+RUN_SCRIPT = """\
+#!/usr/bin/env bash
+# run_checkstyle.sh
+# Runs Checkstyle with the Effective Java configuration against src/
+# Generated by checkstyle_setup.py
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+JAR="${SCRIPT_DIR}/{jar}"
+CONFIG="${SCRIPT_DIR}/effective-java-checkstyle.xml"
+SRC_DIR="${1:-src}"
+
+if [[ ! -f "$JAR" ]]; then
+  echo "ERROR: Checkstyle jar not found at $JAR"
+  echo "Run: python checkstyle_setup.py --output-dir \\"$(dirname "$JAR")\\""
+  exit 1
+fi
+
+if [[ ! -d "$SRC_DIR" ]]; then
+  echo "ERROR: Source directory not found: $SRC_DIR"
+  echo "Usage: ./run_checkstyle.sh [src-dir]"
+  exit 1
+fi
+
+echo "Running Checkstyle on $SRC_DIR ..."
+java -jar "$JAR" -c "$CONFIG" -r "$SRC_DIR"
+echo "Done."
+""".format(jar=CHECKSTYLE_JAR)
+
+
+def download_jar(output_dir: pathlib.Path) -> bool:
+    jar_path = output_dir / CHECKSTYLE_JAR
+    if jar_path.exists():
+        print(f"Checkstyle jar already present: {jar_path}")
+        return True
+    print(f"Downloading Checkstyle {CHECKSTYLE_VERSION} from GitHub ...")
+    try:
+        urllib.request.urlretrieve(CHECKSTYLE_URL, jar_path)
+        print(f"Downloaded: {jar_path}")
+        return True
+    except urllib.error.URLError as exc:
+        print(f"Download failed: {exc}")
+        print()
+        print("To install manually:")
+        print(f"  curl -L -o {jar_path} \\")
+        print(f"    {CHECKSTYLE_URL}")
+        return False
+
+
+def write_file(path: pathlib.Path, content: str, executable: bool = False) -> None:
+    path.write_text(content, encoding="utf-8")
+    if executable:
+        path.chmod(path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    print(f"Wrote: {path}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Set up Checkstyle with an Effective Java-aligned configuration."
+    )
+    parser.add_argument(
+        "--output-dir",
+        default=".",
+        help="Directory to write config files and download the jar (default: ./)",
+    )
+    args = parser.parse_args()
+
+    output_dir = pathlib.Path(args.output_dir).resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    download_jar(output_dir)
+
+    write_file(output_dir / "effective-java-checkstyle.xml", CHECKSTYLE_XML)
+    write_file(output_dir / "run_checkstyle.sh", RUN_SCRIPT, executable=True)
+
+    print()
+    print("Setup complete.")
+    print(f"  Config : {output_dir / 'effective-java-checkstyle.xml'}")
+    print(f"  Runner : {output_dir / 'run_checkstyle.sh'}")
+    print()
+    print("Run Checkstyle:")
+    print(f"  cd {output_dir} && ./run_checkstyle.sh [src-dir]")
+
+
+if __name__ == "__main__":
+    main()

package/skills/effective-java/scripts/example.py

@@ -0,0 +1 @@
+