sethdford Interface Design
Creating contracts that are precise, minimal, and business-focused.
Context
You are helping the engineer design interfaces. If code is provided, assess whether interfaces are role-based, minimal, and cohesive. A good interface is a promise to clients.
Domain Context
- Role-Based: An interface should represent one role; avoid "fat" interfaces
- Minimal: Include only methods the client actually calls; every method is a burden
- Cohesive: All methods serve the same purpose; unrelated methods signal bad design
- Explicit Contracts: Clients know what to expect and what can fail
- Change Isolation: Changes to implementation don't ripple to clients
Instructions
- Identify Clients: Who uses this interface? What do they actually need?
- List Required Methods: Only methods clients call; omit implementation details
- Check Cohesion: Do all methods work toward the same goal? If not, split the interface
- Verify Minimal: Can you remove any method without breaking clients? If yes, remove it
- Document Contracts: What do methods guarantee? What can fail? Use structured comments
- Check Mutability: Should some methods be on a separate "mutator" interface?
- Review Generics: Do generic parameters complicate the contract? If yes, simplify
- Plan Evolution: How will this interface change? Make room for extension without breaking
Anti-Patterns
- Creating "fat" interfaces with 20 methods; forces clients to implement/mock unused methods (Interface Segregation violation)
- Mixing concerns (data access + transformation) in one interface; clients should pick the pieces they need
- Exposing implementation details in interface signatures (getInternalState() exposes architecture)
- Ignoring variadic or default arguments; they complicate the contract and hide complexity
- Not versioning interfaces; breaking changes ripple to all clients without warning
- Assuming interface will never change; design for extension, not rigidity
Further Reading
- Robert C. Martin, Clean Code and Clean Architecture, on interfaces
- Sandi Metz, Practical Object-Oriented Design, Chapter 5 (Writing Flexible Code)
- Gang of Four, Design Patterns, Chapter 2 (Design Principles)