An implementation detail is internal code or design that does not belong to the system’s observable behavior. Observable behavior is what helps a client achieve a goal through a useful operation or state; implementation details are the remaining mechanisms. Public API and observable behavior are separate classifications: a public member can still expose an implementation detail. section 5.2 section 5.5
Figure 5.4. In a well-designed API, the observable behavior coincides with the public API, while all implementation details are hidden behind the private API.
Use the API boundary diagram to distinguish a well-designed public surface, where observable behavior is public and implementation details remain private. section 5.2
Classify code by its purpose and exposure:
- Keep operations and state that help clients achieve their goals in the observable behavior. section 5.5
- Hide mechanisms that merely support those results behind a private API. section 5.5
- Treat a public API that extends beyond observable behavior as a leak; it exposes details clients do not need. section 5.2
- Protect invariants through encapsulation instead of widening the API for tests. section 5.5 section 11.2
Normalize names without leaking the mechanism
A leaking User API exposes NormalizeName, so clients and tests depend on a formatting step. Refactor the class so the Name setter performs normalization privately; callers only assign user.Name = newName. The externally meaningful behavior remains the stored normalized name, while the trimming and length limit become replaceable implementation details. section 5.2
Tests should verify observable results rather than implementation details. Asserting calls to collaborators, exposing private methods, or exposing private state couples tests to intermediate steps and reduces resistance to refactoring. Test private behavior indirectly through the public outcome; if a private method is complex enough to require independent testing, extract its missing abstraction instead. section 5.2 section 11.1
Test the outcome, not Customer status
Customer.Promote changes private status, but production code observes only the discount. Verify that a new customer receives no discount and a promoted customer receives five percent; do not make the status public merely to inspect it. section 11.2


