
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 closure is a function that references variables from the scope in which it was defined. The function and the captured variables form a bundle - the closure retains a live reference to the variable, not a copy of its value at the moment of creation.

<ExamplePair>
<ExampleProse>

A factory function returns a closure that captures a variable from the enclosing scope. Each call to the factory produces a new, independent closure with its own captured state.

</ExampleProse>
<ExampleCode>

```go
package main

import "fmt"

func makeAdder(x int) func(int) int {
    return func(y int) int {
        return x + y
    }
}

func main() {
    add5 := makeAdder(5)
    add10 := makeAdder(10)

    fmt.Println(add5(3))  // 8
    fmt.Println(add10(3)) // 13
    fmt.Println(add5(7))  // 12 - add5 and add10 are independent
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

A closure can capture and mutate a variable in the enclosing scope. Each call to the returned function updates the shared counter.

</ExampleProse>
<ExampleCode>

```go
package main

import "fmt"

func makeCounter() func() int {
    count := 0
    return func() int {
        count++
        return count
    }
}

func main() {
    counter := makeCounter()
    fmt.Println(counter()) // 1
    fmt.Println(counter()) // 2
    fmt.Println(counter()) // 3

    other := makeCounter() // independent counter
    fmt.Println(other())   // 1
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

The goroutine-loop closure bug: on Go versions before 1.22, a goroutine launched inside a loop captures the loop variable itself - a single shared variable - not a snapshot of its value at that iteration. By the time the goroutines run, the loop has finished and every goroutine sees the last value. Go 1.22 changed loop-variable scoping so each iteration gets its own variable, fixing the bug automatically. The safe fix for all versions: pass the loop variable as an argument to the goroutine function literal.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "sync"
)

func main() {
    var wg sync.WaitGroup

    // BUG (Go < 1.22): every goroutine captures the same `i` variable.
    // All likely print 5 (or whatever i is when they run).
    // On Go 1.22+ each iteration gets its own variable, so this is no longer buggy.
    for i := 0; i < 5; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            fmt.Println("buggy:", i) // captures variable, not value (pre-1.22)
        }()
    }
    wg.Wait()

    fmt.Println("---")

    // FIX: pass i as an argument - a copy is made at call time.
    for i := 0; i < 5; i++ {
        wg.Add(1)
        go func(n int) {
            defer wg.Done()
            fmt.Println("fixed:", n) // each goroutine gets its own n
        }(i)
    }
    wg.Wait()
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
The goroutine-loop closure bug is one of the most common sources of data races in real Go services. Before Go 1.22, the loop variable was shared across all iterations - capturing it in a goroutine produced a race between the goroutine read and the loop increment. Go 1.22 changed loop-variable scoping so each iteration gets its own variable, fixing the bug automatically - but services on older toolchain versions (or using `-gcflags=-lang=go1.21` for compatibility) still hit it. The defensive fix - passing the loop variable as an argument - works on all Go versions and is worth making a team habit until you can guarantee Go 1.22+ everywhere.
</InProduction>


Functions that capture and retain their lexical environment - the factory pattern and the goroutine-loop closure pitfall.

Closures


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.