What principles guide designing a good facade over a subsystem in your own Java library, and what failure modes should you avoid?

## Framing: ergonomics layer over a capability layer When you build a library, you have a **capability layer** — the subsystem of focused classes that can do everything the domain requires, expressed in granular, composable pieces. On top you add an **ergonomics layer** — the **facade** — that makes the common workflows a one-liner. The JDK models this perfectly: `FileChannel`/`ByteBuffer`/`Charset` are the capability layer; `java.nio.file.Files` is the ergonomics facade. Good facade design is fundamentally about getting the relationship between these two layers right. ## Design principles 1. **Layer, don't seal.** The single most important rule: a facade *simplifies* access; it must not *remove* it. Keep the subsystem public so advanced callers can drop down for control the facade doesn't expose. The JDK keeps `FileChannel` public beneath `Files`; if it had sealed it, anyone needing memory-mapped I/O would have to abandon the library. A facade that hides its subsystem forces forks and reimplementation. 2. **Intention-revealing, minimal surface.** The facade's methods should read like the caller's *intent* (`copy`, `readString`, `send`), not like the mechanics. Keep the surface small; every method is a maintenance and compatibility commitment. Resist the urge to add a parameter for every subsystem option — that turns the facade back into the subsystem. 3. **Sane defaults for the 80% case.** Choose good defaults (explicit UTF-8 over platform charset, reasonable timeouts, safe buffer sizes) so the facade is correct out of the box. Advanced or unusual needs are intentionally *not* served by the facade — they live in the subsystem. This is the discipline that keeps the facade small. 4. **Statelessness and low coupling.** Prefer a stateless facade (static methods or an immutable, thread-safe object like `HttpClient`) so it is safe to share, easy to reason about, and trivial to test. Inject or construct subsystem dependencies inside it; do not leak them across the facade boundary unless deliberately exposing them. 5. **Dependency direction.** The facade depends on the subsystem, never the reverse. Subsystem classes must not know a facade exists, so the subsystem stays reusable and the facade stays a pure convenience. 6. **Honest resource lifecycle.** If the facade owns a resource, it should close it (like `Files.readAllLines`). If it *returns* a resource-backed object (like `Files.lines` returning a `Stream` over an open file), it must make that ownership obvious (documentation + `AutoCloseable`) so callers don't leak. ## Failure modes to avoid - **The god-object facade.** A facade that accumulates dozens of unrelated methods and that every part of the codebase depends on. This is usually a symptom that the *subsystem boundary is drawn wrong* — too many responsibilities funneled through one type. Split it into cohesive facades per concern. - **The leaky facade.** One that claims to simplify but still requires the caller to understand and manipulate internals (e.g. you must pre-configure three subsystem objects before calling it). If callers can't use the facade without reading the subsystem docs, it isn't simplifying. - **The sealing facade.** One that hides the subsystem entirely, so the moment a caller needs something off the happy path they are stuck. Always provide an escape hatch to the capability layer. - **Resource-hiding facade.** One that obscures whether and when resources are released, causing leaks. Be explicit about ownership. - **Defaults that lie.** Hidden platform-dependent defaults (charset, locale, timezone) that work on the author's machine and break in production. Prefer explicit, deterministic defaults. ## Versioning and evolution Because the facade is what most callers depend on, it is the part most expensive to break. Evolve it additively: new convenience methods are cheap; changing or removing existing ones is a breaking change. Meanwhile the subsystem can refactor more freely *as long as the facade preserves its contract* — which is exactly the decoupling benefit the pattern was meant to buy. A principal-level designer treats the facade's signature set as a long-term public contract and the subsystem as the place where implementation freedom lives. ## The synthesis Facade is not about hiding power; it is about *layering* power so the common path is effortless and the advanced path is still reachable. Get the subsystem boundary right first; the facade then almost designs itself as the thin, intention-revealing skin over it.