go-defensive-coding

Go Defensive Coding

Go has no exceptions and no null-safety in the type system. Every trap below compiles cleanly, passes review, and fails in production.

Detailed reference material, loaded on demand:

• references/nil-and-aliasing.md — the full typed-nil rules, slice aliasing scenarios, and memory retention.
• references/numeric-safety.md — conversion range checks, overflow detection, float and time comparison.

Read a reference file only when the section below is not enough.

Operating Modes

• Harden — you are writing or changing code. Apply every rule as you go.
• Review — you are auditing existing code. Report findings with severity (🔴 panic or corruption, 🟡 latent bug, 🟢 style) and cite file:line.

1. The Typed-Nil Interface Trap

A non-nil interface can hold a nil pointer. This is the single most common source of "impossible" nil checks in Go.

type NotFoundError struct{ ID string }

func (e *NotFoundError) Error() string { return "not found: " + e.ID }

// ❌ Bad — returns a non-nil error even on success
func find(id string) error {
    var err *NotFoundError // typed nil
    if id == "" {
        err = &NotFoundError{ID: id}
    }
    return err // interface is (type=*NotFoundError, value=nil) — NOT nil
}

// ✅ Good — return the untyped nil literal
func find(id string) error {
    if id == "" {
        return &NotFoundError{ID: id}
    }
    return nil
}

Rules:

• Never declare a concrete error/pointer variable and return it as an interface. Return nil explicitly on the success path.
• Never store a possibly-nil concrete pointer in an error, io.Reader, or any interface-typed struct field.
• go vet's nilness analyzer catches some of these. It does not catch all.

2. Nil Map, Slice, and Channel Behaviour

Memorise this table — half of these are safe and half panic or hang.

Operation	nil map	nil slice	nil channel
Read / receive	zero value	index panics	blocks forever
Write / send	panics	append works	blocks forever
len / cap	0	0	0
range	zero iterations	zero iterations	blocks forever
close	n/a	n/a	panics