When should a Go function return `(T, bool)` in comma-ok style instead of `(T, error)`?

## Two conventions, one question Go has no exceptions and no optional type, so a function that might not produce a value says so in its result list. Two shapes dominate: ```go func lookup(key string) (Value, bool) // comma-ok: is there one? func parse(s string) (Value, error) // error: why did it fail? ``` Both are idiomatic. Choosing between them is one of the small API decisions a reviewer will push back on, and the criterion is not difficulty or importance — it is **whether the reason is information**. ## The comma-ok shape: absence is ordinary A `bool` second result carries exactly one bit: the value is real, or it is not. That is the right amount of information when there is only one way to come up empty and the caller already knows what it is. The canonical example is the environment: ```go raw, ok := os.LookupEnv("PORT") ``` `os.Getenv` returns only a string, so an unset variable and one set to `""` are indistinguishable; `os.LookupEnv` adds the bit that separates them. There is nothing to explain — the variable is either in the environment or it is not — so an `error` would be ceremony wrapped around a fact the caller can already state. The shape also reads well at the call site, because Go lets the two-value form drive an `if` with an initialiser: ```go if raw, ok := os.LookupEnv("PORT"); ok { // raw is meaningful only inside this block } ``` The scoping is part of the appeal: the value and the flag that validates it live and die together, so it is hard to use one without having checked the other. When you write your own function in this style, follow the convention exactly: the flag goes **last**, it is named for truth (`ok`, `found`, `present`) rather than for failure, and `true` means the value is usable. A second result that means "something went wrong" inverted from the usual sense will be misread by everyone who has ever written `v, ok :=`. One more rule that is easy to get wrong: when the flag is `false`, return the **zero value** for `T`, not a partially filled one. Callers are entitled to ignore the first result entirely when the second is false, and half-built values leak into code that skipped the check. ## The error shape: the reason is the payload As soon as there is more than one way to fail, or the failure has detail a human or a caller needs, a bool destroys information that cannot be recovered. Consider a config validator that runs as a CI step: ```go func loadConfig(path string) (Config, bool) // "invalid" — but why? func loadConfig(path string) (Config, error) // "open /etc/app.yaml: permission denied" ``` The first version compiles, passes tests, and produces a CI step whose entire output is a red X. The file might be missing, unreadable, malformed, or valid but with an out-of-range timeout, and the engineer on the pull request has to reproduce it locally to find out which. The second version hands the reason to the log line for free. The same reasoning applies inside a function. Reducing an `error` you already hold down to a `false` is the most common way this convention is misused — you had the diagnosis and threw it away. If you catch yourself writing `if err != nil { return zero, false }`, that is the signal to change the signature rather than the branch. ## Cases at the boundary - **Pure, total lookups over data you already have** — an index, a registry, a parsed set — are comma-ok. Failure is "not present", which is not a failure at all. - **Anything touching the filesystem, network, clock, or a parser** is almost always `error`, because the world has many ways to say no. - **Do not return `(T, bool, error)`.** Three results asking the caller to check two conditions is a signature that has not decided what it means. Pick one; if you truly need "absent" and "broken" as different outcomes, an `error` value the caller can test for a specific sentinel case expresses it in two results. - **Do not make the bool mean "error"**, and do not order it first. The convention is load-bearing: readers pattern-match on `v, ok :=` and stop reading. ## What interviewers listen for A strong answer names a real example on each side (`os.LookupEnv` versus `strconv.Atoi`), states the criterion as "can the caller do anything with the reason", and volunteers the anti-pattern of collapsing a known error into a bool. A weak answer treats the choice as taste, or claims `error` is always the safer default — which produces functions whose "error" for an absent optional key forces every caller to compare against a sentinel to find out that nothing is wrong.