
A map is Go's built-in hash table. Keys must be comparable (`==` must work on the type); values can be any type. Reading a missing key always returns the zero value - use the comma-ok idiom to distinguish "key is absent" from "value is zero".

<ExamplePair>
<ExampleProse>

Create a map with `make` or a map literal. Set, get, and delete entries with simple syntax.

</ExampleProse>
<ExampleCode>

```go
package main

import "fmt"

func main() {
    // Map literal
    ages := map[string]int{
        "Alice": 30,
        "Bob":   25,
    }

    // Set
    ages["Carol"] = 28

    // Get
    fmt.Println(ages["Alice"]) // 30

    // Delete
    delete(ages, "Bob")
    fmt.Println(len(ages)) // 2
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Reading a missing key returns the zero value of the value type - `0` for integers, `""` for strings. The comma-ok idiom distinguishes "key is absent" from "value happens to be zero".

</ExampleProse>
<ExampleCode>

```go
package main

import "fmt"

func main() {
    scores := map[string]int{"Alice": 0}

    // Both return 0 - how do you tell them apart?
    a := scores["Alice"]   // 0 (present, value is zero)
    b := scores["Bob"]     // 0 (absent)
    fmt.Println(a, b)      // 0 0

    // Comma-ok tells you definitively
    v, ok := scores["Alice"]
    fmt.Println(v, ok) // 0 true

    v, ok = scores["Bob"]
    fmt.Println(v, ok) // 0 false
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`range` iterates over a map's key-value pairs. Iteration order is randomised on every run - do not rely on it.

</ExampleProse>
<ExampleCode>

```go
package main

import "fmt"

func main() {
    capitals := map[string]string{
        "France":  "Paris",
        "Japan":   "Tokyo",
        "Brazil":  "Brasília",
    }

    for country, city := range capitals {
        fmt.Printf("%s → %s\n", country, city)
    }
    // Order varies every run
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
Maps are not safe for concurrent reads-and-writes. A goroutine writing while another reads causes a data race and a runtime panic (Go detects this since 1.6). Use `sync.RWMutex` to protect maps you share across goroutines, or use `sync.Map` for mostly-read workloads. Reading a missing key silently returns the zero value - a common footgun when the zero value is valid (e.g., `map[string]int` counting occurrences: `m["missing"]` returns `0`, which looks like a valid count). Always check with the comma-ok idiom before acting on the result.
</InProduction>


Key-value stores with make, literals, get/set/delete, the comma-ok idiom, and range iteration.

Maps


Functions are the primary unit of code in Go. Go functions can return multiple values, accept a variable number of arguments, and be assigned to variables or passed as arguments - they are first-class values.

<ExamplePair>
<ExampleProse>

A function declaration names the function, lists its parameters with types, and lists its return types. When there is more than one return value, wrap the types in parentheses.

</ExampleProse>
<ExampleCode>

```go
package main

import "fmt"

// Single return value
func double(n int) int {
    return n * 2
}

// Multiple return values - result and error
func divide(a, b float64) (float64, error) {
    if b == 0 {
        return 0, fmt.Errorf("division by zero")
    }
    return a / b, nil
}

func main() {
    fmt.Println(double(7)) // 14

    result, err := divide(10, 3)
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    fmt.Printf("%.4f\n", result) // 3.3333
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

A variadic function accepts zero or more arguments for its final parameter. Inside the function the variadic parameter behaves as a slice. Pass an existing slice with the `...` spread operator.

</ExampleProse>
<ExampleCode>

```go
package main

import "fmt"

func sum(nums ...int) int {
    total := 0
    for _, n := range nums {
        total += n
    }
    return total
}

func main() {
    fmt.Println(sum(1, 2, 3))       // 6
    fmt.Println(sum(1, 2, 3, 4, 5)) // 15

    nums := []int{10, 20, 30}
    fmt.Println(sum(nums...)) // 60 - spread slice
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Functions are first-class values in Go - you can assign them to variables, pass them as arguments, and return them from other functions. The blank identifier `_` discards an unwanted return value.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "strconv"
)

func apply(f func(int) int, values []int) []int {
    result := make([]int, len(values))
    for i, v := range values {
        result[i] = f(v)
    }
    return result
}

func main() {
    triple := func(n int) int { return n * 3 }

    nums := []int{1, 2, 3, 4}
    fmt.Println(apply(triple, nums)) // [3 6 9 12]

    // _ discards an unwanted return value
    n, _ := strconv.Atoi("42") // discard the error; input is known valid
    fmt.Println(n)             // 42
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
Return `(result, error)` - do not use output parameters (pointer arguments as return slots). Named return values are acceptable at the top of a function as documentation, but naked returns (a bare `return` that uses named results implicitly) in long functions destroy readability and make control flow hard to follow during an incident. Prefer explicit returns in all but the shortest helpers. The [idempotency key pattern](/patterns/idempotency-key) is a case where a clean `(string, error)` signature avoids the temptation to use an in-out pointer parameter that would obscure whether the key was generated or retrieved.
</InProduction>


Declaration, multiple return values, named return values, variadic functions, and functions as first-class values.

Functions


A slice is a view into an underlying array. It has three fields: a pointer to the array, a length, and a capacity. Slices are the workhorse collection in Go - dynamic, passed by reference semantics, and composable.

<ExamplePair>
<ExampleProse>

Create a slice with `make([]T, length, capacity)` or with a slice literal. Both are nil-free and immediately usable. `len` returns the number of elements; `cap` returns the underlying array's size from the slice's start.

</ExampleProse>
<ExampleCode>

```go
package main

import "fmt"

func main() {
    // Slice literal
    s := []int{1, 2, 3}
    fmt.Println(s, len(s), cap(s)) // [1 2 3] 3 3

    // make: length 3, capacity 5
    t := make([]int, 3, 5)
    fmt.Println(t, len(t), cap(t)) // [0 0 0] 3 5
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`append` adds elements to a slice. If the slice has spare capacity, it appends in-place and returns a slice with a larger length. If capacity is exhausted, it allocates a new backing array, copies existing elements, and returns a slice pointing to the new array.

</ExampleProse>
<ExampleCode>

```go
package main

import "fmt"

func main() {
    s := make([]int, 0, 3)

    for i := 0; i < 5; i++ {
        s = append(s, i)
        fmt.Printf("len=%d cap=%d %v\n", len(s), cap(s), s)
    }
    // len=1 cap=3 [0]
    // len=2 cap=3 [0 1]
    // len=3 cap=3 [0 1 2]
    // len=4 cap=6 [0 1 2 3]   ← new backing array allocated
    // len=5 cap=6 [0 1 2 3 4]
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

A sub-slice `s[low:high]` shares the same backing array as the original. Writes through the sub-slice mutate the original. Use `copy` to get an independent slice.

</ExampleProse>
<ExampleCode>

```go
package main

import "fmt"

func main() {
    orig := []int{1, 2, 3, 4, 5}

    // Sub-slice shares backing array
    sub := orig[1:4]   // [2 3 4]
    sub[0] = 99
    fmt.Println(orig)  // [1 99 3 4 5] - original mutated!

    // Independent copy
    dst := make([]int, len(orig))
    copy(dst, orig)
    dst[0] = 0
    fmt.Println(orig)  // [1 99 3 4 5] - original untouched
    fmt.Println(dst)   // [0 99 3 4 5]
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
Two slices sharing a backing array is the most common source of subtle mutation bugs in Go. A sub-slice write reaches through to the parent. In high-throughput services, pre-allocate with `make([]T, 0, n)` when you know the approximate size - it avoids repeated allocations and the GC pressure that comes with them. `append` doubling capacity on each overflow sounds cheap, but 10 000 appends to an unallocated slice trigger ~14 allocations and copies; a single `make` with a sensible capacity eliminates all of them.
</InProduction>


Dynamic sequences built on arrays - make, literals, append, copy, sub-slicing, and the len vs cap distinction.