Slices & Maps — the Reference Gotcha

1 · A slice is a 3-word header over a shared array

This is the one mental model the whole lesson rests on. A Go slice value is not the data — it's a tiny struct: a pointer to a backing array, a length, and a capacity. [Go blog: slices]

Python's list has no such split: a name is always a reference to the one list object. Go copies the header by value — but since the header still points at the same array, an element write reaches through.

def f(xs):
    xs[0] = 99      # caller sees it
    xs.append(7)    # caller sees it too

a = [1, 2, 3]
f(a)              # a == [99, 2, 3, 7]

func f(xs []int) {
    xs[0] = 99           // caller SEES it
    xs = append(xs, 7)  // caller does NOT
}
a := []int{1, 2, 3}
f(a)                      // a == [99, 2, 3]

2 · The append loop — the pattern you'll read constantly

From zeliboba/zemongo/repository.go:65 — decode every cursor row into a result slice.

var models []M                          // nil slice: ptr=nil, len=0, cap=0
for cursor.Next(ctx) {
    model := M(new(T))
    if err := cursor.Decode(model); err != nil {
        return nil, zekit.Error.WrapWithNoMessage(err)
    }
    models = append(models, model)    // grow; reassign the header each time
}

Two things a reviewer reads off this instantly. First, var models []M is a nil slice, not an empty-but-allocated one — and that is fine: append to nil allocates on first use, len(nil)==0, and ranging over nil does nothing. A nil slice is a usable empty slice. Second, models = append(...) reassigns on every iteration because it must (§1) — if you ever see append(models, x) with the result thrown away, that's a bug.

3 · The aliasing hazard — and the repo's defense against it

Because append may reuse the existing backing array (when there's spare capacity), two slices can silently share storage. A sub-slice s[i:j] is the classic trap: it points into s's array. Append to the sub-slice while there's capacity, and you overwrite s's later elements. This survives review because it only bites when capacity happens to allow it.

From zeliboba/zemessage/consumer.go:526 — note how the house code avoids the trap.

if n == len(dependents) {
    c.consumerStates[cid].Dependents = nil
} else {
    c.consumerStates[cid].Dependents =
        append(([]*ElasticConsumerDependent)(nil), dependents[n:]...)
}

Read the right-hand side: append(nil, dependents[n:]...) appends the tail of dependents onto a fresh nil slice. The result gets its own brand-new backing array — it does not alias dependents. A naive dependents[n:] alone would keep pointing into the original array (and keep the whole array alive in memory, even the dropped prefix). This is the idiomatic "copy a slice so the caller can't mutate my array, and I don't pin theirs." [SliceTricks: copy]

4 · Maps — nil reads, but nil writes panic

A map variable's zero value is nil. Reading a nil map is safe (you get the value type's zero value); writing to a nil map is a runtime panic. Python has no equivalent — a dict is either an object or None, and indexing None raises a clear TypeError, not a "this looked like a map" panic.

var m map[string]int   // nil
v := m["x"]            // OK → 0
_, ok := m["x"]       // OK → 0,false
m["x"] = 1            // panic: assignment
                       // to entry in nil map

m := make(map[string]int)
m["x"] = 1            // OK
// or with capacity hint:
m2 := make(map[string]int, len(src))

From zeliboba/zemongo/factory.go:20 — the safe pattern: map field, make'd in the constructor, written under a mutex.

type Factory struct {
    collections map[string]*mongo.Collection
    mutex       sync.Mutex
}
func newFactory(...) *Factory {
    return &Factory{
        collections: make(map[string]*mongo.Collection),  // ← without this, first write panics
    }
}
func (f *Factory) GetCollection(...) (...) {
    f.mutex.Lock(); defer f.mutex.Unlock()
    ...
    f.collections[name] = collection   // safe: map is non-nil, write is guarded
}

5 · Map iteration order is randomized — on purpose

From zeliboba/zemongo/client.go:64.

collections := make(map[string]*mongo.Collection, len(config.Collections))
for id, cc := range config.Collections {   // order is NOT insertion, NOT sorted
    collections[id], err = newCollection(ctx, connection, cc)
    ...
}

Go deliberately randomizes map iteration order — each range over the same map can visit keys in a different sequence. Here it's harmless (each write is independent). But Python 3.7+ guarantees dict preserves insertion order, so a Python engineer's instinct — "I'll just range the map to build an ordered output" — is a real bug in Go. [Go blog: map iteration order]

6 · The reference gotcha — what to flag

7 · Drill — read the reference semantics

Instant feedback. Reps, not grades.

func f(xs []int) {
    xs[0] = 99
    xs = append(xs, 7)
}
a := []int{1, 2, 3}
f(a)

var counts map[string]int
n := counts["a"]
counts["a"] = n + 1

func (c *Cache) Set(key string, vals []int) {
    c.data[key] = vals   // store caller's slice directly
}

Terms introduced

Added to your GLOSSARY.md:

• Slice header — the 3-word value (ptr, len, cap) copied on assignment/pass; the backing array it points to is shared.
• Backing array — the contiguous storage a slice points into; multiple slices can alias the same one.
• nil slice — zero-value slice (var s []T); a usable empty slice — len 0, ranges over nothing, appendable.
• nil map — zero-value map; reads return the zero value, but any write panics. Must be make'd before writing.
• Length vs. capacity — len = elements in use, cap = room before a reallocation; make([]T, len, cap).
• Aliasing — two slices sharing a backing array, so a write or in-capacity append through one is visible through the other.