# Go Glossary

The canonical vocabulary for this workspace. Lessons use *these* words. Definitions are
tight (what the term **is**), opinionated, and reuse other glossary terms on purpose.

## Values & memory

**Value semantics**:
Go copies values on assignment, function call, and return. A function gets a *copy* of
its arguments unless you pass a pointer. The default mental model for everything.
_Avoid_: pass-by-reference (Go has none, except maps/slices/channels' internal headers)

**Pointer**:
A value holding the address of another value (`*T`). The explicit way to share (rather
than copy) a value so a callee can mutate it or avoid copying a large struct.
_Avoid_: reference, address-of (that's the `&` operator)

**Zero value**:
The value a variable has when declared without initialisation — `0`, `""`, `false`,
`nil` for pointers/slices/maps/channels/interfaces, and all-fields-zero for structs. Go
designs types so the zero value is usable ("make the zero value useful").
_Avoid_: default value, empty value

**Receiver**:
The value or pointer a method is attached to — `func (e *Email) FieldMap()`. A *pointer
receiver* can mutate the value and avoids a copy; a *value receiver* operates on a copy.
_Avoid_: this, self

## Composite types

**Struct**:
A typed collection of named fields. Go's aggregate type; assigned and passed by value
(the whole struct is copied) unless via a pointer.
_Avoid_: object, record

**Slice**:
A lightweight *header* — pointer + length + capacity — over a backing array. Copying a
slice copies the header but shares the backing array (aliasing). `append` may reallocate.
_Avoid_: list, dynamic array

**Backing array**:
The fixed-size array a slice's header points into. Two slices can share one; that's why
mutating through one slice can be visible through another.
_Avoid_: underlying buffer

**Capacity**:
How many elements a slice's backing array can hold from the slice's start before
`append` must allocate a new array. Distinct from length.
_Avoid_: size, max length

**Map**:
A reference-like hash table (`map[K]V`). Reading a missing key returns the zero value;
writing to a `nil` map panics. Iteration order is randomised.
_Avoid_: dictionary, hash

## Methods, interfaces, generics

**Interface**:
A set of method signatures. A type satisfies it *implicitly* — no `implements` keyword —
just by having the methods. Idiomatic interfaces are small and declared where consumed.
_Avoid_: contract, protocol, abstract class

**Method set**:
The methods callable on a type. A `*T` has both value- and pointer-receiver methods; a
`T` has only value-receiver methods — which decides whether `T` satisfies an interface.
_Avoid_: vtable

**Nil interface vs nil pointer**:
An interface value is nil only when *both* its type and value are nil. A non-nil
interface can hold a nil concrete pointer — the famous gotcha that makes `err != nil`
true unexpectedly.
_Avoid_: null interface

**Embedding**:
Declaring a type inside a struct (or interface) without a field name, promoting its
fields/methods. Go's composition mechanism — its answer to inheritance.
_Avoid_: inheritance, subclassing

**Generics / type parameter**:
A function or type parameterised by a type (`func Map[T, T2 any](...)`). A *constraint*
(e.g. `any`, `comparable`) limits which types are allowed.
_Avoid_: template, parametric polymorphism (just "generics")

## Concurrency

**Goroutine**:
A function running concurrently, scheduled by the Go runtime onto OS threads — cheap
(starts at ~KBs of stack). Launched with `go f()`.
_Avoid_: thread, coroutine, green thread

**Channel**:
A typed conduit that goroutines send to and receive from, with optional buffering.
Go's primary way to communicate: "share memory by communicating."
_Avoid_: queue, pipe

**select**:
A statement that waits on multiple channel operations, proceeding with whichever is
ready (or a `default`). How goroutines multiplex and honour cancellation.
_Avoid_: poll, switch-on-channels

**Data race**:
Concurrent access to the same memory with at least one write and no synchronisation.
Undefined behaviour; detected with `go test -race`.
_Avoid_: race condition (broader term), concurrency bug

**Context (`context.Context`)**:
A request-scoped value carrying cancellation, deadlines, and values across API
boundaries. Passed as the first argument by convention and honoured via `<-ctx.Done()`.
_Avoid_: request scope, thread-local

## Errors & idioms

**Error (as value)**:
`error` is an ordinary interface (`Error() string`); errors are values returned and
inspected, not thrown. Control flow is explicit `if err != nil`.
_Avoid_: exception

**Wrapping (`%w`)**:
`fmt.Errorf("context: %w", err)` embeds an error so `errors.Is`/`errors.As` can unwrap
it later. Using `%v` instead formats the text but *breaks* the chain.
_Avoid_: rethrow, chaining (say "wrapping")

**Sentinel error**:
A package-level error value (`var ErrNotFound = errors.New(...)`) compared with
`errors.Is`. Signals a specific, expected condition.
_Avoid_: error constant, magic error

**defer**:
Schedules a call to run when the surrounding function returns (LIFO order). Used for
cleanup: `defer span.End()`, `defer cancel()`, `defer rows.Close()`.
_Avoid_: finally

**panic / recover**:
`panic` unwinds the stack; `recover` (only useful in a deferred func) stops it. For
truly exceptional/programmer errors — not ordinary error handling.
_Avoid_: throw/catch

**Functional options**:
A variadic-of-option-funcs API for optional configuration —
`Consume(topic, group, AlwaysCommit(), Instances(2))`. Our repo's config idiom.
_Avoid_: options struct, builder (distinct patterns)

## Repo-specific

**Port / adapter**:
Our hexagonal seam: a *port* is an interface (`infrastructure/repo_port.go`), an
*adapter* is its concrete implementation (a pgx `struct{}`). Interfaces at the seam.
_Avoid_: DAO, gateway

**`database.Ext` / `QueryExecer` / `Tx`**:
Our pgx abstractions injected into repos/handlers. `Ext` is the broad executor;
`QueryExecer` is passed per-method when a transaction must span calls.
_Avoid_: DB handle, connection