go-interfaces

# Go Interfaces and Composition Interfaces in Go are *consumer contracts*, not implementation hierarchies. They should be **small**, **discovered late**, and **owned by the package that uses them** — not the package that satisfies them. ## Core Rules 1. **Accept interfaces, return concrete types.** Consumers state what they need; producers expose what they have. 2. **Interfaces belong in the consumer package.** Defining an interface next to its sole implementation is almost always wrong. 3. **Don't design with interfaces — discover them.** Wait for a second implementation or a test mock to demand one. 4. **The bigger the interface, the weaker the abstraction.** Aim for 1–3 methods; compose larger contracts from smaller ones. 5. **Receiver consistency:** if any method needs a pointer receiver, give *every* method a pointer receiver. 6. **Verify satisfaction at compile time** with `var _ I = (*T)(nil)` when the relationship must not break silently. 7. **Use the comma-ok idiom for every type assertion.** A bare assertion panics on mismatch. ## Decision: Should I Introduce an Interface? | Situation | Verdict | |---|---| | Single implementation, no tests need to swap it | No interface. Use the concrete type. | | Second implementation appears (or is imminent) | Extract an interface in the consumer package. | | Test needs to fake an external dependency | Define a small interface in the consumer; pass a fake. | | You want to expose optional behaviour (`Flusher`, `ReaderFrom`) | ...