Interface-First Design
Definition
Design the feature's public interfaces before writing internals. Interface comments and signatures reveal whether the abstraction is simple, deep, and complete.
Questions To Ask
- What does the caller want to accomplish?
- What inputs are required, and which are implementation details?
- What output, error, or state change should callers observe?
- What ordering must callers not need to know?
- Can the interface comment stay simple?
Existing Project Comparison
- Compare proposed interfaces with current naming, service, command, hook, and repository patterns.
- Flag APIs that expose database shapes, HTTP details, vendor SDKs, or internal steps.
- Look for duplicated or pass-through methods.
Suggestive Plan
- Write the interface name and purpose.
- Draft signature, input, output, errors, and side effects.
- Write the interface comment before implementation.
- Remove parameters that push complexity onto callers.
- Confirm common cases are simple.
Example
Prefer changePreferredWindow(requestId, window, actor) over separate calls for loading request, checking status, validating window, saving, and notifying.
Vocabulary
- Interface: everything callers must know to use a module.
- Informal contract: behavior not expressed in the signature.
- Interface comment: documentation defining the abstraction.
- Common case: normal path the interface should make easy.
Expected Outcome
Produce interface definitions with purpose, inputs, outputs, errors, side effects, comments, and rejected leaks.
1---2name: interface-first-design3description: Design the module interface for one feature before implementation. Use when defining commands, services, hooks, repositories, or public methods so callers see intent rather than implementation details.4---56# Interface-First Design78## Definition910Design the feature's public interfaces before writing internals. Interface comments and signatures reveal whether the abstraction is simple, deep, and complete.1112## Questions To Ask1314- What does the caller want to accomplish?15- What inputs are required, and which are implementation details?16- What output, error, or state change should callers observe?17- What ordering must callers not need to know?18- Can the interface comment stay simple?1920## Existing Project Comparison2122- Compare proposed interfaces with current naming, service, command, hook, and repository patterns.23- Flag APIs that expose database shapes, HTTP details, vendor SDKs, or internal steps.24- Look for duplicated or pass-through methods.2526## Suggestive Plan27281. Write the interface name and purpose.292. Draft signature, input, output, errors, and side effects.303. Write the interface comment before implementation.314. Remove parameters that push complexity onto callers.325. Confirm common cases are simple.3334## Example3536Prefer `changePreferredWindow(requestId, window, actor)` over separate calls for loading request, checking status, validating window, saving, and notifying.3738## Vocabulary3940- Interface: everything callers must know to use a module.41- Informal contract: behavior not expressed in the signature.42- Interface comment: documentation defining the abstraction.43- Common case: normal path the interface should make easy.4445## Expected Outcome4647Produce interface definitions with purpose, inputs, outputs, errors, side effects, comments, and rejected leaks.
harsh817