liveBook · Manning

Implementation detail

As explained in Unit Testing Principles, Practices, and Patterns

An implementation detail is an internal design or coding choice that is not part of software's externally observable behavior.

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

How Unit Testing Principles, Practices, and Patterns covers it

How deep it goes
Defines two classification dimensions, demonstrates API leakage, and applies the distinction to mocks, private methods, and state.
Examples
Uses User.NormalizeName, Customer status, MessageRenderer state, and complex Order pricing to expose or remove internal coupling.
What it assumes
Assumes familiarity with APIs, access modifiers, unit tests, and test doubles while defining observable behavior from first principles.
What you can do after
Evaluate/understand which code belongs in a public API and write tests against observable results without exposing private mechanisms.
How it connects
Connects observable behavior with public API, private API, encapsulation, unit testing, mocks, stubs, and refactoring.

Also explained in

Compare how 3 books explain implementation detail →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Unit Testing Principles, Practices, and Patterns. The section links point to the parts of the book it draws on.