Interfaces on

Lesson 8: Designing Interfaces for Libraries — Libraries export interfaces, apps consume them

Thu, 08 May 2025 00:00:00 +0000

Writing a library for other Go developers is a fundamentally different design problem than writing application code. In an application, you control every call site. If an interface needs to change, you update all the callers. In a library, your callers are other people, other teams, other binaries you have never seen — and when you change a public interface, you break them all in ways you cannot fix yourself. This constraint forces a discipline that makes library-authored Go interfaces among the most carefully designed in the ecosystem.

Lesson 7: The io.Reader/Writer Ecosystem — The most powerful 2-method interfaces in Go

Sat, 08 Mar 2025 00:00:00 +0000

If you want to understand what makes Go interfaces powerful, do not start with your own code. Start with io.Reader. It is one method — Read(p []byte) (n int, err error) — and it is the foundation of an entire ecosystem that spans files, network connections, HTTP bodies, compressed streams, encrypted data, buffered reads, pipes, test helpers, and dozens of third-party libraries. Everything that produces bytes implements io.Reader. Everything that consumes bytes accepts one.

Lesson 6: Testability Without Over-Mocking — Fakes beat mocks every time

Mon, 06 Jan 2025 00:00:00 +0000

Mock frameworks are a seductive solution to a real problem. You have a dependency — a database, an email service, an HTTP client — and you need your tests to run without it. A mock framework promises to solve this with generated code and assertion APIs. In my experience, what actually happens is that the tests become tightly coupled to implementation rather than behavior, they break whenever you refactor internals, and maintaining the mock library becomes a part-time job.

Lesson 5: Composition with Embedding — Small interfaces compose into powerful contracts

Tue, 12 Nov 2024 00:00:00 +0000

One of the things that surprised me most about Go when I came from Python was that Go has no inheritance. No base classes, no method overriding, no type hierarchies. What it has instead is embedding — the ability to include one type inside another so that the outer type promotes the inner type’s methods. Combined with interface composition, this gives you something more flexible than inheritance: you can build complex behaviors from simple, testable pieces without the fragility that comes from deep class trees.

Lesson 4: Returning Concrete Types — Give callers the real thing

Tue, 01 Oct 2024 00:00:00 +0000

There is a piece of Go advice that sounds almost too obvious to state, and yet I see it violated in production codebases every week: return concrete types from your functions. Not interfaces. Not interface{}. The actual, named, exported struct that your function produces.

The reason this feels controversial is that it conflicts with object-oriented instincts. In Java and C#, returning an interface from a factory is considered good practice — it hides the implementation detail and “programs to an interface.” In Go, that instinct leads to information loss, surprise type assertions, and constructors that promise less than they deliver.

Lesson 3: Interface Pollution — More interfaces means more indirection

Thu, 22 Aug 2024 00:00:00 +0000

Interface pollution is not a hypothetical risk. I have walked into codebases where more than half the types in the package are interfaces, where every function parameter is an interface even when the concrete type is never substituted, and where adding a new feature means navigating six files just to trace what a single method call actually does. The code is technically “flexible” in the sense that every seam is abstract. In practice it is a maze with no map.

Lesson 2: Consumer-Side Interfaces — Define where you use, not where you build

Mon, 15 Jul 2024 00:00:00 +0000

There is a convention I spent a long time following without questioning it: put the interface in the same package as the type that implements it. If I had a payment package with a Stripe struct, I would also define PaymentProcessor right there. Callers would import payment.PaymentProcessor. It felt natural — the interface lives next to the thing it describes.

Go’s designers had a different idea in mind, and it took me several refactoring sessions on a real codebase before I understood why it matters: interfaces should be defined by the package that uses them, not the package that implements them. The Go standard library does this consistently and for good reason.

Lesson 1: When NOT to Use Interfaces — Abstractions cost clarity

Sat, 08 Jun 2024 00:00:00 +0000

The first time I saw Go interfaces click in a codebase, I made the same mistake every developer makes: I started reaching for them everywhere. If I had a struct, I made an interface for it. If I had two types that shared even one method name, I defined an interface over both. It felt disciplined. It felt like proper software engineering. It was making my code worse.

The uncomfortable truth about Go interfaces is that they are most powerful when you use them least. Unlike Java, where every class implementing an interface is an explicit declaration, Go interfaces are satisfied implicitly. That means there is almost zero syntax cost to adding one. And that near-zero cost hides the real cost: cognitive overhead, indirection, and the loss of explicit signal about what a piece of code actually does.