Golang Safety

1---2name: golang-safety3description: "Defensive Golang coding to prevent panics, silent data corruption, and subtle runtime bugs. Use whenever writing or reviewing Go code that involves nil-prone types (pointers, interfaces, maps, slices, channels), numeric conversions, resource lifecycle (defer in loops), or defensive copying. Also triggers on questions about nil panics, append aliasing, map concurrent access, float comparison, or zero-value design."4user-invocable: true5license: MIT6compatibility: Designed for Claude Code or similar AI coding agents, and for projects using Golang.7metadata:8  author: samber9  version: "1.1.1"10  openclaw:11    emoji: "🛡️"12    homepage: https://github.com/samber/cc-skills-golang13    requires:14      bins:15        - go16    install: []17allowed-tools: Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*) Agent18---19 20**Persona:** You are a defensive Go engineer. You treat every untested assumption about nil, capacity, and numeric range as a latent crash waiting to happen.21 22# Go Safety: Correctness & Defensive Coding23 24Prevents programmer mistakes — bugs, panics, and silent data corruption in normal (non-adversarial) code. Security handles attackers; safety handles ourselves.25 26## Best Practices Summary27 281. **Prefer generics over `any`** when the type set is known — compiler catches mismatches instead of runtime panics292. **Always use comma-ok for type assertions** — bare assertions panic on mismatch303. **Typed nil pointer in an interface is not `== nil`** — the type descriptor makes it non-nil314. **Writing to a nil map panics** — always initialize before use325. **`append` may reuse the backing array** — both slices share memory if capacity allows, silently corrupting each other336. **Return defensive copies** from exported functions — otherwise callers mutate your internals347. **`defer` runs at function exit, not loop iteration** — extract loop body to a function358. **Integer conversions truncate silently** — `int64` to `int32` wraps without error369. **Float arithmetic is not exact** — use epsilon comparison or `math/big`3710. **Design useful zero values** — nil map fields panic on first write; use lazy init3811. **Use `sync.Once` for lazy init** — guarantees exactly-once even under concurrency39 40## Nil Safety41 42Nil-related panics are the most common crash in Go.43 44### The nil interface trap45 46Interfaces store (type, value). An interface is `nil` only when both are nil. Returning a typed nil pointer sets the type descriptor, making it non-nil:47 48```go49// ✗ Dangerous — interface{type: *MyHandler, value: nil} is not == nil50func getHandler() http.Handler {51    var h *MyHandler // nil pointer52    if !enabled {53        return h // interface{type: *MyHandler, value: nil} != nil54    }55    return h56}57 58// ✓ Good — return nil explicitly59func getHandler() http.Handler {60    if !enabled {61        return nil // interface{type: nil, value: nil} == nil62    }63    return &MyHandler{}64}65```66 67### Nil map, slice, and channel behavior68 69| Type | Read from nil | Write to nil | Len/Cap of nil | Range over nil |70| --- | --- | --- | --- | --- |71| Map | Zero value | **panic** | 0 | 0 iterations |72| Slice | **panic** (index) | **panic** (index) | 0 | 0 iterations |73| Channel | Blocks forever | Blocks forever | 0 | Blocks forever |74 75```go76// ✗ Bad — nil map panics on write77var m map[string]int78m["key"] = 179 80// ✓ Good — initialize or lazy-init in methods81m := make(map[string]int)82 83func (r *Registry) Add(name string, val int) {84    if r.items == nil { r.items = make(map[string]int) }85    r.items[name] = val86}87```88 89See **[Nil Safety Deep Dive](./references/nil-safety.md)** for nil receivers, nil in generics, and nil interface performance.90 91## Slice & Map Safety92 93### Slice aliasing — the append trap94 95`append` reuses the backing array if capacity allows. Both slices then share memory:96 97```go98// ✗ Dangerous — a and b share backing array99a := make([]int, 3, 5)100b := append(a, 4)101b[0] = 99 // also modifies a[0]102 103// ✓ Good — full slice expression forces new allocation104b := append(a[:len(a):len(a)], 4)105```106 107### Map concurrent access108 109Maps MUST NOT be accessed concurrently — → see `samber/cc-skills-golang@golang-concurrency` for sync primitives.110 111See **[Slice and Map Deep Dive](./references/slice-map-safety.md)** for range pitfalls, subslice memory retention, and `slices.Clone`/`maps.Clone`.112 113## Numeric Safety114 115### Implicit type conversions truncate silently116 117```go118// ✗ Bad — silently wraps around if val > math.MaxInt32 (3B becomes -1.29B)119var val int64 = 3_000_000_000120i32 := int32(val) // -1294967296 (silent wraparound)121 122// ✓ Good — check before converting123if val > math.MaxInt32 || val < math.MinInt32 {124    return fmt.Errorf("value %d overflows int32", val)125}126i32 := int32(val)127```128 129### Float comparison130 131```go132// ✗ Bad — floating point arithmetic is not exact1330.1+0.2 == 0.3 // false134 135// ✓ Good — use epsilon comparison136const epsilon = 1e-9137math.Abs((0.1+0.2)-0.3) < epsilon // true138```139 140### Division by zero141 142Integer division by zero panics. Float division by zero produces `+Inf`, `-Inf`, or `NaN`.143 144```go145func avg(total, count int) (int, error) {146    if count == 0 {147        return 0, errors.New("division by zero")148    }149    return total / count, nil150}151```152 153For integer overflow as a security vulnerability, see the `samber/cc-skills-golang@golang-security` skill section.154 155## Resource Safety156 157### defer in loops — resource accumulation158 159`defer` runs at _function_ exit, not loop iteration. Resources accumulate until the function returns:160 161```go162// ✗ Bad — all files stay open until function returns163for _, path := range paths {164    f, _ := os.Open(path)165    defer f.Close() // deferred until function exits166    process(f)167}168 169// ✓ Good — extract to function so defer runs per iteration170for _, path := range paths {171    if err := processOne(path); err != nil { return err }172}173func processOne(path string) error {174    f, err := os.Open(path)175    if err != nil { return err }176    defer f.Close()177    return process(f)178}179```180 181### Goroutine leaks182 183→ See `samber/cc-skills-golang@golang-concurrency` for goroutine lifecycle and leak prevention.184 185## Immutability & Defensive Copying186 187Exported functions returning slices/maps SHOULD return defensive copies.188 189### Protecting struct internals190 191```go192// ✗ Bad — exported slice field, anyone can mutate193type Config struct {194    Hosts []string195}196 197// ✓ Good — unexported field with accessor returning a copy198type Config struct {199    hosts []string200}201 202func (c *Config) Hosts() []string {203    return slices.Clone(c.hosts)204}205```206 207## Initialization Safety208 209### Zero-value design210 211Design types so `var x MyType` is safe — prevents "forgot to initialize" bugs:212 213```go214var mu sync.Mutex   // ✓ usable at zero value215var buf bytes.Buffer // ✓ usable at zero value216 217// ✗ Bad — nil map panics on write218type Cache struct { data map[string]any }219```220 221### sync.Once for lazy initialization222 223```go224type DB struct {225    once sync.Once226    conn *sql.DB227}228 229func (db *DB) connection() *sql.DB {230    db.once.Do(func() {231        db.conn, _ = sql.Open("postgres", connStr)232    })233    return db.conn234}235```236 237### init() function pitfalls238 239→ See `samber/cc-skills-golang@golang-design-patterns` for why init() should be avoided in favor of explicit constructors.240 241## Enforce with Linters242 243Many safety pitfalls are caught automatically by linters: `errcheck`, `forcetypeassert`, `nilerr`, `govet`, `staticcheck`. See the `samber/cc-skills-golang@golang-linter` skill for configuration and usage.244 245## Cross-References246 247- → See `samber/cc-skills-golang@golang-concurrency` skill for concurrent access patterns and sync primitives248- → See `samber/cc-skills-golang@golang-data-structures` skill for slice/map internals, capacity growth, and container/ packages249- → See `samber/cc-skills-golang@golang-error-handling` skill for nil error interface trap250- → See `samber/cc-skills-golang@golang-security` skill for security-relevant safety issues (memory safety, integer overflow)251- → See `samber/cc-skills-golang@golang-troubleshooting` skill for debugging panics and race conditions252 253## Common Mistakes254 255| Mistake | Fix |256| --- | --- |257| Bare type assertion `v := x.(T)` | Panics on type mismatch, crashing the program. Use `v, ok := x.(T)` to handle gracefully |258| Returning typed nil in interface function | Interface holds (type, nil) which is != nil. Return untyped `nil` for the nil case |259| Writing to a nil map | Nil maps have no backing storage — write panics. Initialize with `make(map[K]V)` or lazy-init |260| Assuming `append` always copies | If capacity allows, both slices share the backing array. Use `s[:len(s):len(s)]` to force a copy |261| `defer` in a loop | `defer` runs at function exit, not loop iteration — resources accumulate. Extract body to a separate function |262| `int64` to `int32` without bounds check | Values wrap silently (3B → -1.29B). Check against `math.MaxInt32`/`math.MinInt32` first |263| Comparing floats with `==` | IEEE 754 representation is not exact (`0.1+0.2 != 0.3`). Use `math.Abs(a-b) < epsilon` |264| Integer division without zero check | Integer division by zero panics. Guard with `if divisor == 0` before dividing |265| Returning internal slice/map reference | Callers can mutate your struct's internals through the shared backing array. Return a defensive copy |266| Multiple `init()` with ordering assumptions | `init()` execution order across files is unspecified. → See `samber/cc-skills-golang@golang-design-patterns` — use explicit constructors |267| Blocking forever on nil channel | Nil channels block on both send and receive. Always initialize before use |