Generic Functions and Type Parameters

A package needs IndexOf for []string, []int, and two domain slices. The first version is written three times with four-character differences. The fourth copy is where the bugs start: someone copies the []string version, changes the comparison, forgets one call site, and a lookup silently scans the wrong slice.

The any-based workaround compiles and loses the type check:

func IndexAny(s []any, v any) int {
	for i, x := range s {
		if x == v {
			return i
		}
	}
	return -1
}

names := []any{"ada", "grace"}
_ = IndexAny(names, 42) // compiles; will never match; no error anywhere

Callers must wrap every value in any, the compiler stops checking that the element type and the target match, and == on interface values panics at runtime when the boxed dynamic type is uncomparable — a slice or map sitting in that any turns a lookup into a crash. A type parameter fixes all three:

func IndexOf[T comparable](s []T, target T) int {
	for i, v := range s {
		if v == target {
			return i
		}
	}
	return -1
}

func Contains[T comparable](s []T, target T) bool {
	return IndexOf(s, target) != -1
}

The bracketed [T comparable] is the type parameter list. Inside the body, T behaves like an ordinary type name: it can be an element type, a parameter type, a result type, and — subject to the constraint — the operand of ==. The body is written once and checked once against the constraint, not against string or int: the compiler verifies that every operation the body uses is permitted for any type the constraint admits. Instantiating IndexOf[string] and IndexOf[int] reuses that checked body.

At the call site, the type arguments are almost always unnecessary:

i := IndexOf(names, "grace")      // T inferred as string from both arguments
j := IndexOf([]int{10, 20}, 20)   // T inferred as int
k := Contains(cookies, "session") // inference flows through a named slice type

Inference reads the ordinary arguments and solves for T. When every argument agrees, you write the call like any other function; the explicit form IndexOf[string](names, "grace") exists for the cases inference cannot cover, which the second half of this topic takes apart.

One design note that shapes everything after: Contains calls IndexOf with T — inside a generic function, a type parameter can be passed where a type is expected, so generic code composes with generic code without any extra machinery. This is the whole feature in one page: one body, static checking at every call, and no runtime dispatch.

The constraint is the part of the contract the compiler enforces, and there are only three shapes you will use for functions.

comparable is the built-in constraint for types that support == and !=. Slices, maps, and functions are not comparable, so IndexOf([][]int{{1}}, []int{1}) fails at the call site — the same lookup that would panic with the any version is rejected at compile time. That static rejection is the entire reason comparable exists.

any (an alias for interface{}) constrains nothing: every type qualifies. It is the right bracket when the body never inspects the value — passing it through, storing it, formatting it with %v. It is the wrong bracket the moment the body calls a method:

func Describe[T fmt.Stringer](items []T) string {
	var b strings.Builder
	for _, it := range items {
		b.WriteString(it.String()) // legal: every T has a String() method
		b.WriteByte('\n')
	}
	return b.String()
}

An interface written inside the brackets constrains by method set: only types whose method set includes String() string may be instantiated, and the body may call those methods on a T value. This differs from passing []fmt.Stringer — with the generic version, the element type survives: Describe([]User{...}) returns results you can still use as []User's values, and the caller never boxes each element into an interface. Type sets (unions like ~int | ~string) are the fourth shape, and the constraints topic takes them apart with the standard library's cmp and slices packages.

Inference has edges worth knowing by sight. It works from ordinary arguments; it fails when there is nothing to read T from:

func NewQueue[T any]() *Queue[T] { return &Queue[T]{} }

q := NewQueue()          // no arguments: nothing to infer from — error
q := NewQueue[string]()  // explicit type argument: correct

It also steps back when the argument would need conversion, or when T appears only in the result:

var zero T               // T only as a result type: specify it, e.g. zeroValue[int]()
il := IndexOf([]int{}, x) // fine — inference reads the slice's element type

And inference never widens: if one argument says int and the other says float64, there is no implicit conversion — IndexOf(floats, 1) fails because 1 would have to become a float64, and Go does not insert that conversion for you. Explicit type arguments (IndexOf[float64](f, 1)) are the escape hatch, and an untyped constant is the common reason you reach for it.

The check that ties it together: after instantiation, the call site must satisfy the constraint and the arguments must be assignable without hidden conversions. When a generic call fails to compile, read the error as one of those two questions — is T wrong for the bracket, or is an argument of the wrong type?

A team replaces every small interface with a generic function. Six months later, a plugin system that needed runtime substitution no longer has an interface to implement, and three functions carry four type parameters each because the generic versions grew parameters the originals never had. Generics and interfaces solve different problems, and the choice is answerable before writing code.

Generics collapse code that is identical across types. The body is the same algorithm — index a slice, sort with a comparison, map values into a new slice — and the only variation is which type flows through. There is no dispatch at runtime, no value boxed into an interface, and callers keep the concrete type in their signatures:

func Map[T, U any](s []T, f func(T) U) []U {
	out := make([]U, len(s))
	for i, v := range s {
		out[i] = f(v)
	}
	return out
}

emails := Map(users, func(u User) string { return u.Email }) // []string, statically

Interfaces vary behavior at runtime. When different types implement different logic, or a value's dynamic type is only known at call time, an interface is the mechanism — it is what makes http.Handler, fmt.Stringer, and storage fakes work. A generic function cannot decide between implementations based on a value's runtime type; it was chosen at compile time. The shape renderer below needs an interface:

type Shape interface {
	Area() float64
}

func TotalArea(shapes []Shape) float64 {
	var sum float64
	for _, s := range shapes {
		sum += s.Area() // each element dispatches to its own implementation
	}
	return sum
}

[]Shape holds a circle and a rectangle in the same slice; a TotalArea[T] could only accept one element type, and mixing them would force boxing back into any.

The three-question decision. Is the logic the same for every type? Use generics. Do different types do different things, or must the choice happen at runtime? Use an interface. Is the difference one type switch on two or three cases with no shared body? A plain switch in an ordinary function beats both — generics pay a readability cost (longer errors, brackets at call sites) that one branch does not justify.

A pragmatic hybrid exists: keep the narrow consumer-side interface for boundaries where substitution matters, and write generic helpers for the data manipulation inside. The standard library itself follows this — slices.SortFunc is generic over elements while io.Writer stays an interface for streams. Where the element types and their constraints are the story rather than the plumbing, the constraints and collections topic is next.