Go Generics

Go Generics and Type Parameters

Compatibility: Generics require Go 1.18+.

Resource Routing

• references/CONSTRAINTS.md - Read when composing constraints, using type sets, or choosing between generics and interfaces.

When to Use Generics

Start with concrete types. Generalize only when a second type appears.

Prefer Generics When

• Multiple types share identical logic (sorting, filtering, map/reduce)
• You would otherwise rely on any and excessive type switching
• You are building a reusable data structure (concurrent-safe set, ordered map)

Avoid Generics When

• Only one type is being instantiated in practice
• Interfaces already model the shared behavior cleanly
• The generic code is harder to read than the type-specific alternative

"Write code, don't design types." — Robert Griesemer and Ian Lance Taylor

Decision Flow

Do multiple types share identical logic?
├─ No  → Use concrete types
├─ Yes → Do they share a useful interface?
│        ├─ Yes → Use an interface
│        └─ No  → Use generics

Bad:

// Premature generics: only ever called with int
func Sum[T constraints.Integer | constraints.Float](vals []T) T {
    var total T
    for _, v := range vals {
        total += v
    }
    return total
}

Good:

func SumInts(vals []int) int {
    var total int
    for _, v := range vals {
        total += v
    }
    return total
}

---

Type Parameter Naming

For complex constraints, a short descriptive name is acceptable:

func Marshal[Opts encoding.MarshalOptions](v any, opts Opts) ([]byte, error)

---

Type Aliases vs Type Definitions

Type aliases (type Old = new.Name) are rare — use only for package migration or gradual API refactoring.

---

Constraint Composition

Combine constraints with ~ (underlying type) and | (union):

type Numeric interface {
    ~int | ~int8 | ~int16 | ~int32 | ~int64 |
    ~float32 | ~float64
}

func Sum[T Numeric](vals []T) T {
    var total T
    for _, v := range vals {
        total += v
    }
    return total
}

Use the constraints package or cmp package (Go 1.21+) for standard constraints like cmp.Ordered instead of writing your own.

---

Common Pitfalls

Don't Wrap Standard Library Types

// Bad: generic wrapper adds complexity without value
type Set[T comparable] struct {
    m map[T]struct{}
}

// Better: use map[T]struct{} directly when the usage is simple
seen := map[string]struct{}{}

Generics justify their complexity when they eliminate duplication across multiple call sites. A single-use generic is just indirection.

Don't Use Generics for Interface Satisfaction

// Bad: T is only used to satisfy an interface — just use the interface
func Process[T io.Reader](r T) error { ... }

// Good: accept the interface directly
func Process(r io.Reader) error { ... }

Avoid Over-Constraining

// Bad: constraint is more restrictive than needed
func Contains[T interface{ ~int | ~string }](slice []T, target T) bool { ... }

// Good: comparable is sufficient
func Contains[T comparable](slice []T, target T) bool { ... }

---

Quick Reference

---

Related Skills

• Interfaces vs generics: See go-interfaces when deciding whether an interface already models the shared behavior without generics
• Type declarations: See go-declarations when defining new types, type aliases, or choosing between type definitions and aliases
• Documenting generic APIs: See go-documentation when writing doc comments and runnable examples for generic functions
• Naming type parameters: See go-naming when choosing names for type parameters or constraint interfaces

Type Constraints in Go Generics

Sources: Google Go Style Guide, Go language specification

Constraints define what operations a type parameter supports. Choose the narrowest constraint that satisfies your function's needs — no more.

---

Built-in Constraints

Normative: Use standard constraints before writing your own.

Prefer cmp.Ordered (from cmp package) over the deprecated golang.org/x/exp/constraints.Ordered for new code.

---

The ~ Operator (Underlying Types)

Advisory: Use ~ when you want to accept named types built on a

primitive.

The ~T syntax matches any type whose underlying type is T. Without ~, only the exact type matches.

type Celsius float64

type ExactFloat interface{ float64 }   // rejects Celsius
type AnyFloat64 interface{ ~float64 }  // accepts Celsius

Use ~ when callers are likely to define named types over the base type. Omit ~ only when you need to restrict to the exact built-in type.

---

Composing and Writing Constraints

Advisory: Define a custom constraint only when no standard one fits.

Combine types with | and embed constraints to compose them:

type Numeric interface {
    ~int | ~int8 | ~int16 | ~int32 | ~int64 |
    ~float32 | ~float64
}

type Addable interface {
    Numeric | ~string  // numbers and string concatenation
}

Constraints can require methods alongside type elements:

type Stringer interface {
    comparable
    String() string
}

A type satisfying Stringer must be comparable and have a String() method.

---

Avoiding Over-Constraining

Normative: Use the minimal constraint that supports the operations

you perform.

Bad

// Only uses == but restricts to int and string
func Contains[T interface{ ~int | ~string }](s []T, v T) bool { ... }

Good

// comparable is the minimal constraint for ==
func Contains[T comparable](s []T, v T) bool { ... }

Over-constraining limits reuse and forces callers to work around restrictions that the implementation never needed.

Type Inference

Advisory: Let the compiler infer type arguments when unambiguous.

The compiler infers type parameters from function arguments:

result := slices.Contains[string](names, "alice")  // explicit — unnecessary
result := slices.Contains(names, "alice")           // inferred — preferred

Supply type arguments explicitly only when there are no function arguments to infer from, the inferred type is wrong (e.g., untyped constant promotes to the wrong type), or readability benefits from making the type visible.

---

Common Pitfalls

Don't Use Generics When Interfaces Suffice

Normative: From Google Style Guide — prefer interfaces when types

share a useful unifying interface.

Bad

// T is only used to satisfy io.Reader — just use the interface
func Process[T io.Reader](r T) error { ... }

Good

func Process(r io.Reader) error { ... }

If the constraint is a single existing interface, accept the interface directly.

Don't Wrap Standard Library Types Generically

Advisory: A single-use generic is just indirection.

Bad

type Set[T comparable] struct{ m map[T]struct{} }  // only ever Set[string]

Good

seen := map[string]struct{}{}  // use map directly for a single instantiation

Generics justify complexity when they eliminate duplication across multiple call sites. If only one type is ever used, start concrete.

Method Sets and Type Constraints

You can only call operations the constraint allows:

Bad

func Stringify[T any](v T) string {
    return v.String()  // compile error: any does not have String()
}

Good

func Stringify[T fmt.Stringer](v T) string {
    return v.String()
}

---

Quick Reference