Idiomatic API and Package Design

A payment client ships with a tempting signature:

func NewClient() *Client // returns Client with nil http.Client, nil logger, nil clock

The README shows c := NewClient(); c.Charge(...). Three teams discover at runtime which fields they forgot to set — each hitting a nil dereference in a different method, in production, weeks apart. The signature promised a client and delivered an object that must be assembled correctly by convention. Every one of those failures traces to the same design error: the zero value of the struct is not usable, but the API allows returning it.

Go offers two honest answers, and the package must pick one.

A required-dependency constructor fails loudly:

package payments

type Client struct {
	http  *http.Client
	base  *url.URL
	clock func() time.Time
}

func NewClient(baseURL string, hc *http.Client) (*Client, error) {
	u, err := url.Parse(baseURL)
	if err != nil {
		return nil, fmt.Errorf("payments: bad base URL %q: %w", baseURL, err)
	}
	if hc == nil {
		hc = &http.Client{Timeout: 10 * time.Second}
	}
	return &Client{http: hc, base: u, clock: time.Now}, nil
}

The invariants live in the constructor: the URL parses, the HTTP client exists, the clock is set. After NewClient succeeds, no method needs a nil guard — and if it fails, the caller has an error at wiring time, not a panic at charge time. Returning (*Client, error) costs callers an if err != nil and saves them an entire class of bugs.

A zero-value-usable type skips the constructor entirely, which is the stdlib's preferred shape when no validation is needed:

var buf bytes.Buffer      // usable immediately, no New
var mu sync.Mutex         // zero value is an unlocked mutex
var m map[string]string   // needs make, but not a constructor

bytes.Buffer has no New() because its zero value is valid. If your type has an unusable zero value, that is a signal: either add a constructor that enforces the dependencies (as above) or restructure so the zero value works.

Two conventions finish the discipline. Pointer or value return? Return a pointer when the type has identity — mutable state, fields that must not be copied — and a value when it is small and copyable, matching Value Semantics versus Pointers. Name the constructor for the package, not the type: inside payments, payments.NewClient stutters; stdlib precedent is payments.New(...), sql.Open, time.ParseDuration — the package is already half the identifier. And for errors that callers must branch on, define sentinels or types the caller can match with errors.Is/errors.As (The error Interface and Error Messages), rather than forcing text matching on constructor failures.

The cache constructor starts reasonable — NewCache(addr string, db int, ttl time.Duration, maxItems int) — and then adds a namespace, a password, a dial timeout, and a retry count. At seven parameters, every call site is a line of positional arguments where swapping db and ttl compiles cleanly and fails at runtime. The design question is not "struct or options?" but how much will this grow, and how clearly can callers see which argument is which?

Three shapes cover the realistic cases:

The config struct is the workhorse:

type Config struct {
	Addr     string        // required
	DB       int           // required
	TTL      time.Duration // optional, 0 means default
	Password string        // optional
}

func New(cfg Config) (*Cache, error) {
	if cfg.Addr == "" {
		return nil, errors.New("cache: Addr is required")
	}
	if cfg.TTL == 0 {
		cfg.TTL = time.Minute
	}
	return &Cache{...}, nil
}

Named fields survive insertion of new options: adding MaxItems next year changes one struct, not five call sites. Validation stays in one place.

Functional options earn their complexity when the API is exported and parameters will keep arriving:

type Option func(*Cache) error

func WithTTL(d time.Duration) Option {
	return func(c *Cache) error {
		if d <= 0 {
			return fmt.Errorf("ttl must be positive, got %s", d)
		}
		c.ttl = d
		return nil
	}
}

func New(addr string, opts ...Option) (*Cache, error) {
	c := &Cache{addr: addr, ttl: time.Minute}
	for _, o := range opts {
		if err := o(c); err != nil {
			return nil, fmt.Errorf("cache: %w", err)
		}
	}
	return c, nil
}

The cost is real: options are harder to read in godoc, they let callers pass the same option twice, and every With* is permanent API. Reach for them when the alternative is a breaking signature change each release.

The rule that outranks all three: interfaces belong on the consumer side, and you return concrete types.

// producer package: returns the concrete type
cache := redis.New(addr)

// consumer package: declares only what IT needs
type Getter interface {
	Get(ctx context.Context, key string) ([]byte, error)
}

func render(g Getter, key string) ([]byte, error) { ... }

Returning *redis.Cache keeps the producer free to add methods; declaring Getter where it is used keeps the consumer's requirement minimal — the interface-segregation half of Accept interfaces, return structs. Exported methods are forever: an added method is compatible, a changed signature is not. Before exporting anything, ask whether an unexported method or a new package could serve internal needs — because in Go's compatibility promise, the cheapest API to maintain is the one you did not publish.

The code review request adds one method to a widely used package. The diff is small; the comment is not: "renaming this exported method breaks every caller — did we consider deprecating instead?" Package design in Go is mostly about which changes become breaking later, and the leverage points are naming, placement, and documentation.

Names: short, lowercase, no stutter. The package name is already the prefix, so user.New() beats user.NewUser(), user.Type beats user.UserType — the stdlib pattern is http.Request, not http.HTTPRequest, and tls.Client, not tls.TLSClient. Package names should be single lowercase words that say what the package provides (ring, filepath, template); if you cannot name it in one word, it may be two packages. Avoid util, common, and helpers — they are where names from unrelated domains collide.

Placement decides visibility more than exported/unexported does. Go's rule is lexical: identifiers are visible to their package, and packages are the unit of encapsulation. This means API design is file and package design:

// internal/secrets/ — invisible to every importer outside this module
package secrets

type Provider interface { Get(ctx context.Context, key string) ([]byte, error) }

The internal/ directory enforces an architectural boundary the compiler checks: code outside cannot import it at all, so an implementation detail cannot leak through an exported function by accident. When a helper is needed by exactly one package, it stays unexported; when two packages need it, it moves to a shared package with a name that describes the concept, not the coincidence of reuse.

Documentation is part of the signature. Go doc comments read as sentences starting with the identifier — // Cache is a bounded key-value store... for a type, // New returns a Cache backed by addr... for a function. The comment should state the contract the compiler cannot: what happens on failure, whether the zero value works, whether the returned value is safe for concurrent use, who closes what. The most valuable sentences are the negative ones — // New does not dial; connections are established lazily on first use prevents a misunderstanding no type can express.

Change-resistance is measured by asking what a plausible future edit would break. Add a field to an exported struct literal used positionally? Callers who construct with Config{Addr: x, DB: 1} by field name survive; Config{x, 1} breaks. Add a method to an exported interface? Every implementer outside the package breaks — which is why Interfaces and Type Assertions warns to define interfaces where they are consumed: your own consumer interfaces are yours to grow, and exported ones belong to implementers you do not control. Remove a parameter? Breaks everyone. Introduce one? Breaks no one. The design goal is a surface where the common evolution — adding — is always the safe one, and the rare evolution — removal — requires a deprecation cycle and a major version. Every export is a promise; count them before making it.