Scope and Shadowing Rules

## What `:=` actually does A short variable declaration (`x := expr`) is a *declaration*, not an assignment. Go's declaration rules say that an identifier declared inside a function is scoped to the innermost block that contains the declaration — a block being anything between `{` and `}`: a function body, an if body, an else branch, a for body, a switch case, or a bare `{ … }`. The scope starts at the end of the declaration itself and ends at that block's closing brace. So when a name already exists further out and you write `:=` inside a nested block, you get two distinct variables with the same name. The inner one *shadows* the outer one: for the rest of that block, the name refers to the new variable, and when the block ends, the new variable is gone and the name refers to the outer variable again — unchanged. ```go n := 1 { n := 2 // a second variable, also called n n++ // touches the inner one only _ = n } // n is still 1 here ``` ## Why the compiler stays silent Two Go rules make this easy to write by accident and hard to notice: 1. **Shadowing is legal.** It is not a warning, not a vet check in the default set, and not a style violation the compiler knows about. Inner scopes hiding outer names is a normal, useful feature — it is how a small helper variable in a loop body avoids colliding with anything else. 2. **The unused-variable error does not fire.** Go refuses to compile a declared-but-unused local, which catches many typos. But a shadowed variable is usually *used* inside its block (checked, logged, returned from the block), so the rule is satisfied and the code builds. ## The redeclaration rule people misremember Go allows `:=` to appear with a name that already exists, on one condition: at least one non-blank name on the left must be new, and the reused names must have been declared *earlier in the same block* with the same type. When that holds, the reused name is simply assigned — no second variable appears. ```go a, err := strconv.Atoi("1") // a and err are both new b, err := strconv.Atoi("2") // b is new; err is assigned ``` That behaviour is what makes the shadowing case surprising. Developers internalise "`:=` reuses `err`" from same-block code, then carry the intuition across a brace, where it stops being true: inside a nested block, *every* name on the left is new, because the reuse rule requires the same block. ## Where it bites The classic shape is a value that must survive the block — most often an error, sometimes a result or a counter: ```go var err error if needsPatch { err := writeHunk(h) // new err, dies at the brace if err != nil { return nil // or: log and carry on } } return err // the outer err, still nil ``` The program is well-typed, the tests over the happy path pass, and the failure is reported as success. ## How to write it so the question does not arise - Use `=` when you mean the variable that already exists. If no such variable is in scope, the compiler tells you immediately — a useful, cheap check. - Give inner values their own names (`writeErr`, `parseErr`) when they genuinely are a different thing. Two variables with the same name in one function is a readability cost even when it is correct. - Declare a variable in the narrowest scope that needs it. Most accidental shadows come from an outer variable that was hoisted further out than necessary. - Keep functions short enough that both declarations fit on one screen. Shadowing is nearly invisible when the two declarations are eighty lines apart. ## One detail worth knowing Because the new variable's scope begins *at the end* of the declaration, the right-hand side still sees the outer variable. `x := x` inside a nested block is legal and idiomatic: it makes a local copy of the outer `x`. That is the same rule read from the other direction — the inner name does not exist yet while its own initialiser is being evaluated.