Go Generics and Type Parameters

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

Name

Typical Use

T

General type parameter

K

Map key type

V

Map value type

E

Element/item type

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.

Read references/CONSTRAINTS.md when writing custom type constraints, composing constraints with ~ and |, or debugging type inference issues.

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

Topic

Guidance

When to use generics

Only when multiple types share identical logic and interfaces don't suffice

Starting point

Write concrete code first; generalize later

Naming

Single uppercase letter (T, K, V, E)

Type aliases

Same type, alternate name; use only for migration

Constraint composition

Use ~ for underlying types,

Common pitfall

Don't genericize single-use code or when interfaces suffice

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