go-declarations

Go Declarations and Initialization

Pick the simplest declaration form that expresses your intent: scope variables tightly, group related declarations, and let the zero value do its job.

Core Rules

1. := for locals with values; var for intentional zero values or top-level declarations.
2. Group related declarations in parenthesized blocks. Separate unrelated ones into distinct blocks.
3. Start enums at iota + 1 so the zero value is "invalid/unset" — unless zero is genuinely meaningful.
4. Initialize structs with field names. Omit zero-value fields; let defaults speak.
5. Use any, not interface{}, in all new code.
6. Never shadow builtins (len, cap, error, new, make, copy, any, nil, ...).

Decision: var vs :=

Context	Use	Example
Package-level	var (always)	var startTime = time.Now()
Local with computed value	:=	s := "foo"
Local zero-value, intentional	var	var filtered []int
Declared type differs from RHS	var T = expr	var e error = f()

Read references/scope-and-shadowing.md when fighting subtle bugs caused by := redeclaring an outer variable.

Group Related Declarations

// Bad
const a = 1
const b = 2

// Good
const (
    a = 1
    b = 2
)

Inside functions, group adjacent vars even if loosely related:

var (
    caller  = c.name
    format  = "json"
    timeout = 5 * time.Second
)

Constants and iota

Zero is the default; reserve it for "uninitialized" by starting enums at iota + 1:

type Operation int

const (
    Add      Operation = iota + 1 // 1
    Subtract                      // 2
    Multiply                      // 3
)

Use plain iota only when the zero value is the sensible default (e.g., LogToStdout = iota).

Read references/iota-and-literals.md for bitmask enums, String() methods, raw strings, and composite-literal formatting.