Describe Interfaces First

Design the caller's contract before implementation details make the current shape feel inevitable.

Activation evidence

Apply this principle before implementing an interface when current-task evidence shows both:

1. the interface is public, crosses a module or ownership seam, or has behavior that is not obvious from established types and conventions; and
2. callers must understand at least one meaningful guarantee, error, side effect, ordering rule, lifecycle constraint, or invariant to use it correctly.

A function, class, component, package entry point, service API, event, command, or data exchange can be an interface. Materially changing an existing contract activates the principle just as creating one does.

Decision rule

Describe the caller contract before the body, use that description to improve the design, and keep non-obvious guarantees canonical as the implementation evolves.

The tempting default is to implement first and add comments that narrate the mechanics afterward. Replace it with this short design probe: