In TypeScript, when is it worth writing an explicit return type annotation on a function, and when is letting the compiler infer it the better choice?

## What the annotation changes Without an annotation the compiler *reports* the function's return type: it reads the body, unions the return expressions, and that becomes the signature. With an annotation the direction reverses — the compiler *checks* the body against the type you wrote, and the type you wrote is what callers see regardless of what the body happens to produce today. That difference in direction is the whole argument. Everything below follows from it. ## Reason one: errors land at the definition With an inferred return type, a mistake in the body is not an error at all — it just changes the function's type, and the complaint surfaces wherever a caller uses the result. On a widely-used helper that means a dozen errors, none of them in the file you edited. ```ts type Status = "open" | "closed"; function label(status: Status): string { if (status === "open") return "Open"; // error here: not every code path returns a string } ``` Annotated, the missing branch is an error on `label` itself: the function lacks an ending return statement and the declared return type does not include `undefined`. (That check depends on `strictNullChecks`; without it, `undefined` is assignable to `string` and the branch slips through.) Unannotated, the inferred type would quietly become `string | undefined` and the failure would move to whichever caller wrote `label(s).toUpperCase()`. ## Reason two: it pins the contract For an exported function the return type *is* the API. Inference means the API is whatever the current implementation computes, so an innocent-looking change to the body is an API change: - a callback that starts returning `T | null` silently widens the exported type; - returning the whole record instead of a projection leaks internal fields to every consumer; - an internal type used in the return position becomes part of your published surface whether you meant it to or not. Annotating states the contract independently of the implementation. The refactor that would have widened it now fails inside the function, which is where you can still make a decision about it. ```ts interface User { id: string; secretHash: string } function publicUser(u: User): { id: string } { return u; // returning more than promised is fine; callers see only { id: string } } ``` ## Reason three: recursion Inference cannot resolve a return type that depends on itself. A function referenced in one of its own return expressions has no fixed point to compute, and under `noImplicitAny` the compiler says so directly — the function implicitly has return type `any` because it lacks an annotation and is referenced in one of its return expressions. The annotation breaks the cycle: ```ts type Node = { children: Node[] }; function depth(node: Node): number { if (node.children.length === 0) return 1; return 1 + Math.max(...node.children.map(depth)); } ``` Mutual recursion between two functions has the same problem and the same fix. ## Reason four, a smaller one: build behaviour When a package emits declaration files, every exported function's return type has to appear in the output. If it is inferred, the compiler must compute it and name every type it references, which can drag awkward imports into the declaration output and, on a large surface, costs time. Explicit return types on the exported layer make that emit deterministic. This is a real effect, but it is the weakest of the four reasons — use it as supporting evidence, not as the argument. ## The case for inference Inference is not the lazy option; frequently it is the more accurate one. - **It is often narrower than what you would write.** Generic helpers, functions returning tuples, and functions whose result depends on narrowing all infer types that are tedious and error-prone to write out. Annotating them is how you accidentally widen your own code. - **It cannot drift.** An annotation is a second statement of the truth, and second statements go stale. When a small internal helper changes shape, inference propagates the change and the checker finds every consequence; an annotation has to be edited too. - **It is less noise.** On a small local helper the annotation restates a single-expression body word for word. The cost of inference is exactly the flip side of reasons one and two: a mistake becomes a type change instead of an error, and the blast radius is however far the value travels. ## Async functions An annotated async function's return type must be a promise type, so you write `Promise<T>` and never the bare `T`. That does not change any of the reasoning above; it only means the contract you pin is the promise's, and a mismatch between the annotation and what the body resolves to is caught in the body. ## A defensible policy Annotate: exported functions and public class methods, recursive and mutually recursive functions, and any function whose correct return type is a design decision rather than an implementation detail. Infer: local helpers, callbacks and arrows in contextual positions, and anything whose inferred type is more precise than what you would write. If you want the rule enforced rather than remembered, a lint rule can require return types on exported functions only — the variant that requires them everywhere is the one teams regret, because it forces hand-written approximations of types the compiler already knew exactly.