Variáveis em Golang: var, :=, valores zero e sombreamento

Go tem duas formas de declarar uma variável: var, que funciona em qualquer lugar, e :=, uma forma curta que funciona dentro de funções e infere o tipo.

package main

import "fmt"

func main() {
	var city string = "Lisbon" // explicit type and value
	var year = 2026            // type inferred as int
	var score int              // no value: zero value 0
	name := "Ana"              // short declaration, inferred string

	fmt.Println(city, year, score, name)
	fmt.Printf("%T %T %T %T\n", city, year, score, name)
}

Toda variável tem um tipo fixo, decidido em tempo de compilação. Quando você fornece um valor, o Go infere o tipo a partir dele, então escrever o tipo também (var city string = "Lisbon") é válido, mas redundante.

var ou :=

A escolha idiomática dentro de uma função:

• x := valor quando você tem um valor inicial.
• var x T quando você quer o valor zero, o que sinaliza "vazio de propósito": var buf bytes.Buffer, var total int.
• var x T = valor quando o tipo inferido não é o que você quer, por exemplo var ratio float64 = 1 (um simples ratio := 1 seria um int).

:= fora de uma função é erro de sintaxe:

./main.go:5:1: syntax error: non-declaration statement outside function body

Valores zero

Uma variável declarada sem valor nunca contém lixo. Ela guarda o valor zero do seu tipo:

package main

import "fmt"

type Point struct {
	X, Y int
}

func main() {
	var i int
	var f float64
	var b bool
	var s string
	var p *int
	var sl []int
	var m map[string]int
	var pt Point

	fmt.Println(i, f, b, s == "", p, sl == nil, m == nil, pt)
	fmt.Println(len(sl), len(m), m["missing"])
}

Boas APIs em Go são projetadas para que o valor zero seja útil: um sync.Mutex zero está destravado, um bytes.Buffer zero está vazio e pronto para uso, e len, range e append funcionam em um slice nil. O caso de atenção é o map: ler um map nil devolve valores zero, mas escrever nele causa panic. Crie maps com make ou com um literal antes de gravar neles.

Declarando várias variáveis

package main

import "fmt"

var (
	appName = "inventory"
	version = "1.4.0"
	debug   bool
)

func main() {
	var width, height int = 1920, 1080
	x, y := 3, 4
	first, count := "widget", 12

	fmt.Println(appName, version, debug)
	fmt.Println(width, height, x, y, first, count)

	// swap without a temporary variable
	x, y = y, x
	fmt.Println("after swap:", x, y)
}

O bloco var ( ... ) agrupa variáveis de nível de pacote relacionadas. Em uma atribuição múltipla como x, y = y, x, todas as expressões da direita são avaliadas antes de qualquer atribuição, e é por isso que a troca funciona.

:= com vários nomes não redeclara nada desde que pelo menos um nome à esquerda seja novo. Os nomes que já existem no mesmo escopo simplesmente recebem o valor. É isso que permite reutilizar err:

f, err := os.Open("a.txt")   // declares f and err
g, err := os.Open("b.txt")   // declares g, assigns to the existing err

Se nenhum dos nomes for novo, dá erro:

./main.go:7:4: no new variables on left side of :=

Use o = simples para atribuir a uma variável que já existe.

Variáveis sem uso são erros

Uma variável local declarada e nunca lida interrompe o build:

./main.go:9:2: declared and not used: x

Não é um aviso que dá para desligar. Apague a variável, use-a ou, durante a depuração, silencie-a com o identificador em branco: _ = x. O identificador em branco também descarta valores de retorno de que você não precisa: _, err := fmt.Println("hi").

Variáveis de nível de pacote e parâmetros de função ficam fora dessa regra.

Escopo e sombreamento (shadowing)

Uma variável existe da sua declaração até o fim do bloco que a contém ({ ... }). Um := em um bloco interno cria uma variável nova, mesmo que exista uma com o mesmo nome do lado de fora. A de fora fica sombreada, não alterada:

package main

import (
	"fmt"
	"strconv"
)

func main() {
	count := 0
	input := "42"

	if input != "" {
		count, err := strconv.Atoi(input) // new count, only inside this block
		if err != nil {
			fmt.Println("error:", err)
			return
		}
		fmt.Println("inside:", count)
	}

	fmt.Println("outside:", count) // still 0
}

O programa imprime inside: 42 e depois outside: 0. O := dentro do if declarou count e err como variáveis novas no bloco interno, porque nenhuma das duas existia ali ainda. Compila sem erro e é uma fonte clássica de bugs do tipo "meu valor sumiu".

A correção é declarar err antes e atribuir com =:

var err error
count, err = strconv.Atoi(input)

go vet não reporta shadowing por padrão. O analisador separado shadow reporta, e linters como o golangci-lint podem ativá-lo.

Nomes

• Use camelCase: maxRetries, userID. Não max_retries.
• Mantenha siglas em uma só caixa: userID, httpClient, parseURL, e não userId.
• Nomes curtos para escopos curtos: i em um laço, r para um reader, err para um erro. Nomes mais longos e descritivos para variáveis de nível de pacote.
• Um nome com inicial maiúscula no nível de pacote (var Timeout) é exportado para outros pacotes. Veja pacotes e imports.

Variáveis de nível de pacote

Variáveis declaradas fora de funções vivem durante todo o programa e são inicializadas antes de main rodar, na ordem das dependências. Elas são práticas para configuração e caches, e são compartilhadas por todas as goroutines. Se mais de uma goroutine escreve em uma delas, proteja-a com um mutex ou use sync/atomic; do contrário você tem uma data race.

Prefira constantes para valores que nunca mudam. Uma const não pode ser alterada por acidente e não custa nada em tempo de execução.