Your Go client library takes a Config with a Timeout time.Duration — how do you tell 'unset' from an explicit zero?

## The root of the problem Go guarantees that every field of a struct is set to its type's zero value, and it offers no way to mark a field as absent, optional or defaulted in its declaration. That gives you a very pleasant property — no uninitialised memory — and takes one away: `Config{}` and `Config{Timeout: 0}` are bit-for-bit identical. Nothing downstream can distinguish "the caller did not think about this" from "the caller asked for zero". For a library author this is a design decision you make once per exported field and cannot quietly change later, because the meaning of zero is part of your public contract. ## Why it is dangerous rather than merely annoying The standard library shows the failure mode. `http.Client.Timeout` is documented so that zero means *no timeout at all*. So the caller who wrote `client := &http.Client{}` and moved on has not chosen a sensible default; they have chosen to wait forever. `http.Server`'s `ReadTimeout`, `WriteTimeout` and `IdleTimeout` behave the same way. A wrong zero taken as a real setting does not produce an error at the point of the mistake — it produces a hung request, or an unbounded resource, at 3am. So the question is not academic taste. It is: when a caller of your SDK forgets a field, do they get a safe default or a hazard? ## Shape one: zero means "use the default" Make the zero value mean the sensible thing, and normalise at the point of use or in your constructor. ```go const defaultTimeout = 30 * time.Second const noTimeout = time.Duration(-1) type Config struct { // Timeout of 0 selects defaultTimeout; use noTimeout to disable it. Timeout time.Duration } func (c Config) resolvedTimeout() time.Duration { switch c.Timeout { case 0: return defaultTimeout case noTimeout: return 0 } return c.Timeout } ``` Strengths: literals stay clean, the type has a usable zero value, and forgetting the field is safe. Cost: the caller has lost the ability to say zero directly, so you must give them a sentinel, and the sentinel must be documented on the field itself. Normalise in one place — a private accessor or a single `withDefaults` step — rather than sprinkling `if c.Timeout == 0` through the package, or the meaning of zero will drift between call sites. This shape is the right default for a field where zero is a hazard (timeouts, limits, buffer sizes) and where a genuine zero is rare. ## Shape two: a pointer field ```go type Config struct { Retries *int } ``` Now nil means unset and a non-nil pointer means the caller chose a value, zero included. This is the only shape that represents the distinction directly in the type. It is also the shape that decoding forces on you. With `encoding/json`, an absent key leaves the field untouched — so a pointer field stays nil for `{}` and points at 0 for `{"retries":0}`. With a plain `int` you literally cannot tell those apart after decoding, which matters for partial-update or patch-style payloads. Costs: an allocation and a nil check at every read, and literals get awkward because you cannot take the address of a constant inline without a helper. Keep pointer fields to the handful where absence is genuinely meaningful. ## Shape three: option functions ```go type Option func(*Config) func WithTimeout(d time.Duration) Option { return func(c *Config) { c.Timeout = d } } func New(opts ...Option) *Client { cfg := Config{Timeout: defaultTimeout} for _, o := range opts { o(&cfg) } return &Client{cfg: cfg} } ``` Defaults live in one place, and only the settings a caller actually names are overwritten, so "unset" is expressed by not calling the option at all. This also lets you add settings later without breaking any existing call site. The cost is more API surface and a config that is harder to build from a decoded file, since a file has to be translated into options. ## Shape four: an explicit presence flag A paired `Timeout time.Duration` plus `TimeoutSet bool`, or a wrapper in the style of `database/sql`'s `sql.NullInt64`, encodes presence beside the value. It is verbose and easy to get out of sync, but it survives copying and comparison better than a pointer does, and it is sometimes the right answer for a struct that crosses a serialisation boundary. ## Make the zero path testable Whatever you choose, exercise it. The bug hides in the path nobody writes a test for, because tests tend to construct fully populated structs. Add a test that builds the type the way a hurried caller will — `var c Client`, or `New(Config{})` — and asserts the behaviour you promised: that the default timeout is applied, that no request can hang, that a zero limit is not treated as "unlimited" by accident. That single test is what turns a documented convention into an enforced one. ## What to write down Every exported field whose zero value is meaningful gets a doc comment saying so, in the form the standard library uses: what zero selects, and how to express the other case. Reviewers can then check the contract instead of guessing it, and the decision stops being re-litigated per pull request.