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

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):