go

name	Go
slug	go
version	1.0.2
description	Write reliable Go code avoiding goroutine leaks, interface traps, and common concurrency bugs.
metadata	{"clawdbot":{"emoji":"🐹","requires":{"bins":["go"]},"os":["linux","darwin","win32"]}}

Quick Reference

Topic	File
Concurrency patterns	concurrency.md
Interface and type system	interfaces.md
Slices, maps, strings	collections.md
Error handling patterns	errors.md

Goroutine Leaks

• Goroutine blocked on channel with no sender = leak forever—always ensure channel closes or use context
• Unbuffered channel send blocks until receive—deadlock if receiver never comes
• for range on channel loops forever until channel closed—sender must close(ch)
• Context cancellation doesn't stop goroutine automatically—must check ctx.Done() in loop
• Leaked goroutines accumulate memory and never garbage collect

Channel Traps

• Sending to nil channel blocks forever—receiving from nil also blocks forever
• Sending to closed channel panics—closing already closed channel panics
• Only sender should close channel—receiver closing causes sender panic
• Buffered channel full = send blocks—size buffer for expected load
• select with multiple ready cases picks randomly—not first listed

Defer Traps

• Defer arguments evaluated immediately, not when deferred function runs—defer log(time.Now()) captures now
• Defer in loop accumulates—defers stack, run at function end not iteration end
• Defer runs even on panic—good for cleanup, but recover only in deferred function
• Named return values modifiable in defer—defer func() { err = wrap(err) }() works
• Defer order is LIFO—last defer runs first

Interface Traps

• Nil concrete value in interface is not nil interface—var p *MyType; var i interface{} = p; i != nil is true
• Type assertion on wrong type panics—use comma-ok: v, ok := i.(Type)
• Empty interface any accepts anything but loses type safety—avoid when possible
• Interface satisfaction is implicit—no compile error if method signature drifts
• Pointer receiver doesn't satisfy interface for value type—only *T has the method

Error Handling

• Errors are values, not exceptions—always check returned error
• err != nil after every call—unchecked errors are silent bugs
• errors.Is for wrapped errors—== doesn't work with fmt.Errorf("%w", err)
• Sentinel errors should be var ErrFoo = errors.New() not recreated
• Panic for programmer errors only—return error for runtime failures

Slice Traps

• Slice is reference to array—modifying slice modifies original
• Append may or may not reallocate—never assume capacity
• Slicing doesn't copy—a[1:3] shares memory with a
• Nil slice and empty slice differ—var s []int vs s := []int{}
• copy() copies min of lengths—doesn't extend destination

Map Traps

• Reading from nil map returns zero value—writing to nil map panics
• Map iteration order is random—don't rely on order
• Maps not safe for concurrent access—use sync.Map or mutex
• Taking address of map element forbidden—&m[key] doesn't compile
• Delete from map during iteration is safe—but add may cause issues

String Traps

• Strings are immutable byte slices—each modification creates new allocation
• range over string iterates runes, not bytes—index jumps for multi-byte chars
• len(s) is bytes, not characters—use utf8.RuneCountInString()
• String comparison is byte-wise—not Unicode normalized
• Substring shares memory with original—large string keeps memory alive

Struct and Memory

• Struct fields padded for alignment—field order affects memory size
• Zero value is valid—var wg sync.WaitGroup works, no constructor needed
• Copying struct with mutex copies unlocked mutex—always pass pointer
• Embedding is not inheritance—promoted methods can be shadowed
• Exported fields start uppercase—lowercase fields invisible outside package

Build Traps

• go build caches aggressively—use -a flag to force rebuild
• Unused imports fail compilation—use _ import for side effects only
• init() runs before main, order by dependency—not file order
• go:embed paths relative to source file—not working directory
• Cross-compile: GOOS=linux GOARCH=amd64 go build—easy but test on target