When should you reach for a static nested class instead of a top-level class, and what are real-world examples?

## The decision in one sentence Use a **static nested class** when a type is *conceptually part of* another class and would not stand on its own, but does *not* need access to a specific instance of that class. ## First, the alternatives you're choosing between - **Top-level class**: a normal class in its own right, named directly in a package. Best when the type is independently meaningful and reusable. - **Static nested class**: a `static` member class. Best for a subordinate helper bound to one enclosing class but not to an instance. - **Non-static inner class**: a member class *with* the implicit enclosing-instance reference. Use only when each helper instance is conceptually 'owned by' a specific outer object and needs its instance fields. - **Local / anonymous class**: defined inside a method; for one-off, scope-limited use. ## When a static nested class wins 1. **Strong cohesion, no independent meaning.** If `Builder` only makes sense as the builder *of* `Foo`, nesting it as `Foo.Builder` documents that bond in the type name itself. 2. **You want privileged access to the outer class's private statics.** A nested class can read the enclosing class's private static fields/methods (and vice versa), enabling tight collaboration without widening visibility for the whole package. 3. **You want to hide the helper entirely.** A `private static` nested class (e.g. a `Node`) is invisible outside the enclosing class — perfect for internal data structures. 4. **Namespace hygiene.** Nesting keeps the package's top-level namespace uncluttered when a type is an implementation detail or a sub-part. ## Canonical real-world examples - **`Map.Entry`** — a public static nested interface representing a key/value pair, meaningful only relative to `Map`. - **Builder pattern** — `StringBuilder`-style fluent builders are frequently `Outer.Builder` static nested classes (e.g. many `@Builder`-generated and hand-written builders). - **Data-structure nodes** — `private static class Node<E>` inside a linked list, tree, or hash map bucket array. - **Comparators / strategies** tightly bound to a type, exposed as `Type.SomeComparator`. - **Typed result/holder objects** returned by a class's methods. ## When NOT to nest - The type is genuinely reusable elsewhere → make it **top-level** so it's discoverable and not coupled to an unrelated parent. - It needs the enclosing *instance* → it's a real **inner class** (but reconsider the design first). - Nesting would bloat an already large class or hide an important public type → split it out. ## Trade-offs to weigh - **Pro:** cohesion, encapsulation (private nesting), namespacing, access to outer privates, no separate file to manage. - **Con:** larger source files, slightly less discoverable than a top-level type, and the `$` binary name surfaces in reflection/serialization/stack traces. ## Defined terms - **Cohesion**: how strongly the responsibilities of a unit belong together; high cohesion is desirable. - **Encapsulation**: hiding internal details behind a boundary; `private static` nesting maximizes it. - **Builder pattern**: an object that accumulates configuration and produces a fully constructed target object, improving readability over telescoping constructors. ## The senior heuristic Default to **static** nesting for subordinate helpers; escalate to a top-level class when the type earns independent reuse, and drop to a non-static inner class only when you truly need the enclosing instance. Match the nesting to the conceptual ownership, not to convenience.