Skip to content

Table of Contents

🧠 Knowledge Base (Atomic Notes)

A growing graph of small, linked "atomic" notes — one idea each — distilled from daily journal entries. This is the long-term memory of the repo. Link notes with [[wikilink]] style references and keep each entry short enough to recall.

Conventions

  • One concept per entry. Title it as a claim or question.
  • Add the date first learned + a link to the day note.
  • Cross-link related notes: Related: [[slice-internals]], [[append-aliasing]].
  • Promote stable notes here from the journal; promote the densest ones into cheatsheets/.

Index by Topic

zero-values

Every type has a usable zero value (0, "", false, nil). Design types so the zero value is useful — e.g. sync.Mutex and bytes.Buffer work without initialization. Related: [[slice-internals]]

slice-internals

A slice is a 3-word header: pointer to a backing array, length, capacity. Multiple slices can share one backing array — mutating one can affect another. Related: [[append-aliasing]], [[zero-values]]

value-vs-pointer-receivers

Pointer-receiver methods are in the method set of *T only; value-receiver methods are in both T and *T. To mutate the receiver or avoid copying large structs, use a pointer receiver. Be consistent within a type. Related: [[interface-satisfaction]]

interface-satisfaction

A type satisfies an interface implicitly by having all its methods — no implements keyword. Define interfaces where they're consumed, keep them small. Related: [[nil-interface-trap]]

nil-interface-trap

An interface holding a nil pointer is not == nil (it has a type but no value). Returning a typed nil pointer as an error makes err != nil true — a classic bug.

errors-are-values

Errors are ordinary values returned as the last result. Handle or return them; don't panic in libraries. if err != nil is the idiom. Related: [[error-wrapping]]

error-wrapping

Wrap with fmt.Errorf("doing x: %w", err) to preserve the chain; inspect with errors.Is(err, target) and errors.As(err, &target). Use errors.Join for multiple. Related: [[errors-are-values]]

channel-axioms

Send/receive on a nil channel blocks forever; closing a closed channel panics; sending on a closed channel panics; receiving from a closed channel returns the zero value with ok=false immediately. Related: [[goroutine-leaks]]

goroutine-leaks

A goroutine blocked forever (e.g. on a channel nobody will send to, or an un-cancelled context) leaks. Always give every goroutine a guaranteed exit path. Related: [[context-first-param]], [[channel-axioms]]

context-first-param

ctx context.Context is the first parameter, never stored in a struct. Use it for cancellation, deadlines, and request-scoped values only.

⬅ README · Quick reference lives in cheatsheets/