Boas Práticas Fundamentais de Go

Q: Por que atribuir resultados de append?

append pode realocar e retornar um cabeçalho de slice diferente. Ignorar o retorno deixa você apontando para capacidade ou dados obsoletos.

Q: O que pertence a cmd/ vs. raiz do pacote?

cmd//main.go contém executáveis; código de biblioteca vive em pacotes importáveis na raiz do módulo ou pkg/ por convenção da equipe.

Q: Slice nil é aceitável em APIs JSON?

Slices nil geralmente codificam como null; slices vazios como []. Escolha intencionalmente para contratos de API e documente a escolha.

Hábitos essenciais que todo desenvolvedor Go deve internalizar primeiro.

Estas regras reforçam os fundamentos da seção: nomes claros, tratamento explícito de erros nas fronteiras e coleções usadas com suas semânticas reais.

Como Usar Esta Lista

Aplique durante a revisão de código e ao aprender um novo repositório - não como uma lista de verificação única.
Prefira gofmt, go vet e golangci-lint para capturar violações automaticamente.
Quando uma regra conflitar com dados de desempenho medidos, documente a exceção em um comentário ou ADR.
Revise após grandes atualizações do Go; o toolchain e os idiomatismos da biblioteca padrão evoluem lentamente, mas mudam.

A - Nomenclatura e declarações

Use nomes curtos e significativos em escopos pequenos e nomes mais longos no escopo do pacote. Locais como i e err são aceitáveis em loops; APIs exportadas merecem nomes descritivos.
Prefira := dentro de funções quando o tipo for óbvio. Reserve var para declarações em nível de pacote e valores zero intencionais.
Exporte apenas o que os chamadores precisam. Identificadores maiúsculos são uma promessa de compatibilidade - mantenha as superfícies exportadas pequenas.
Agrupe constantes relacionadas com iota. Evite números mágicos espalhados na lógica; nomeie estados e flags explicitamente.
Evite variáveis mutáveis em nível de pacote, a menos que sincronizadas. Passe dependências através de construtores e parâmetros de função em vez de globais ocultos.

B - Tipos, valores zero e coleções

Projete structs para que os valores zero sejam úteis quando possível. Os chamadores não devem precisar sempre de um construtor para tipos simples.
Inicialize mapas com make ou literais antes de escrever. Nunca atribua a um mapa nil.
Trate len(string) como comprimento de byte, não contagem de caracteres. Use range ou utf8.RuneCountInString para texto visível ao usuário.
Pré-aloque slices quando o tamanho for conhecido. make([]T, 0, n) reduz as alocações em loops críticos.
Atribua o resultado de append. s = append(s, x) porque append pode retornar um novo cabeçalho.

C - Ponteiros, structs e APIs

Use receptores de ponteiro quando os métodos modificam o estado. Mantenha receptores de valor para tipos imutáveis pequenos, a menos que a consistência exija ponteiros.
Passe ponteiros para structs grandes apenas após profiling ou necessidades claras de mutação. Use valores como padrão para registros pequenos.
Verifique ponteiros nil antes de desreferenciar nas fronteiras da API. Documente se as funções aceitam nil para parâmetros opcionais.
Incorpore tipos deliberadamente, não para falsa herança. Métodos promovidos devem ser lidos como capacidades naturais do tipo externo.
Prefira campos de struct nomeados em literais. Literais posicionais quebram quando os campos são reordenados ou adicionados.

D - Pacotes, layout e ferramentas

Mantenha main enxuto; coloque a lógica em pacotes importáveis. Um módulo pode hospedar pontos de entrada cmd/ e código de biblioteca lado a lado.
Use internal/ para código que não deve vazar entre módulos. Deixe o compilador impor limites em vez de apenas comentários.
Execute go fmt ./... antes de cada commit. Formatação consistente remove debates de estilo na revisão.
Execute go test ./... e go vet ./... em CI. Erros fundamentais devem falhar rapidamente na automação.
Fixe versões de módulos em go.mod e comite go.sum. Builds reproduzíveis começam com um grafo de módulos limpo.

FAQs

Devo sempre usar ponteiros para structs?

Não - structs pequenas são mais baratas por valor.

Use ponteiros para mutação, campos opcionais ou custo de cópia comprovado.

É errado usar variáveis em nível de pacote?

Constantes e variáveis somente leitura são aceitáveis.

Estado de pacote mutável requer sincronização e prejudica a testabilidade - evite, a menos que esteja encapsulando primitivas sync por design.

Quando devo usar arrays em vez de slices?

Raramente - tamanhos fixos de rede, blocos criptográficos ou restrições incorporadas.

Use slices como padrão para código de aplicação.

Quão rigoroso deve ser o embedding?

Incorpore quando o tipo externo expõe genuinamente o comportamento incorporado (Server registra via Logger incorporado).

Use campos nomeados quando a relação for "tem um", não "se comporta como".

Por que atribuir resultados de append?

append pode realocar e retornar um cabeçalho de slice diferente.

Ignorar o retorno deixa você apontando para capacidade ou dados obsoletos.

Devo nomear todos os valores de retorno?

Retornos nomeados ajudam na documentação em funções pequenas; evite quando obscurecem a clareza.

Código fundamental deve favorecer return x, err explícito.

Como evitar bugs de variáveis de loop em goroutines?

Passe variáveis de loop como parâmetros de função.

No Go 1.22+, variáveis por iteração reduzem o risco, mas parâmetros explícitos permanecem mais claros.

O que pertence a cmd/ vs. raiz do pacote?

cmd/<app>/main.go contém executáveis; código de biblioteca vive em pacotes importáveis na raiz do módulo ou pkg/ por convenção da equipe.

Slice nil é aceitável em APIs JSON?

Slices nil geralmente codificam como null; slices vazios como [].

Escolha intencionalmente para contratos de API e documente a escolha.

Quando devo usar internal/?

Sempre que o código não puder ser importado por outros módulos - auxiliares vinculados a um produto, não um SDK público.

Preciso de construtores para todas as structs?

Apenas quando validação ou invariantes são necessários.

Prefira valores zero úteis para structs de configuração simples.

Como as melhores práticas se relacionam com golangci-lint?

Ative linters como govet, staticcheck e errcheck para impor muitos desses hábitos automaticamente em CI.

Relacionado

Fundamentos Básicos de Go - Introdução executável cobrindo esses hábitos em código
Como os Programas Go São Estruturados - Modelo mental de layout de pacote e toolchain
Variáveis, Constantes e Escopo - Regras de declaração e escopo em profundidade
Valores Zero e Inicialização - Padrões seguros e padrões make
Ponteiros e o Operador de Endereço - Quando os ponteiros valem sua complexidade

Links Relacionados Externos

Effective Go - Guia oficial para escrever Go claro e idiomático.
Go Wiki – Learn - Recursos de aprendizado curados pela comunidade.
Learn Go with Tests - Introdução ao Go focada em TDD.
Learning Go (2ª Edição, O'Reilly) - Jon Bodner na O'Reilly.
Concurrency in Go - Katherine Cox-Buday.

Versões de Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, go fix modernizers - verifique o patch na compilação), chi (última versão - verifique na compilação), gin (última versão - verifique na compilação), echo (última versão - verifique na compilação), google.golang.org/grpc (última versão - verifique na compilação), sigs.k8s.io/controller-runtime (última versão - verifique na compilação), kubebuilder (última versão - verifique na compilação), tinygo (última versão - verifique os alvos de placa na compilação), wazero (última versão - verifique na compilação) e golangci-lint (última versão - verifique o conjunto de linters na compilação).

Boas Práticas Fundamentais de Go

Hábitos essenciais que todo desenvolvedor Go deve internalizar primeiro.

Estas regras reforçam os fundamentos da seção: nomes claros, tratamento explícito de erros nas fronteiras e coleções usadas com suas semânticas reais.

Como Usar Esta Lista

Aplique durante a revisão de código e ao aprender um novo repositório - não como uma lista de verificação única.
Prefira gofmt, go vet e golangci-lint para capturar violações automaticamente.
Quando uma regra conflitar com dados de desempenho medidos, documente a exceção em um comentário ou ADR.
Revise após grandes atualizações do Go; o toolchain e os idiomatismos da biblioteca padrão evoluem lentamente, mas mudam.

A - Nomenclatura e declarações

Use nomes curtos e significativos em escopos pequenos e nomes mais longos no escopo do pacote. Locais como i e err são aceitáveis em loops; APIs exportadas merecem nomes descritivos.
Prefira := dentro de funções quando o tipo for óbvio. Reserve var para declarações em nível de pacote e valores zero intencionais.
Exporte apenas o que os chamadores precisam. Identificadores maiúsculos são uma promessa de compatibilidade - mantenha as superfícies exportadas pequenas.
Agrupe constantes relacionadas com iota. Evite números mágicos espalhados na lógica; nomeie estados e flags explicitamente.
Evite variáveis mutáveis em nível de pacote, a menos que sincronizadas. Passe dependências através de construtores e parâmetros de função em vez de globais ocultos.

B - Tipos, valores zero e coleções

Projete structs para que os valores zero sejam úteis quando possível. Os chamadores não devem precisar sempre de um construtor para tipos simples.
Inicialize mapas com make ou literais antes de escrever. Nunca atribua a um mapa nil.
Trate len(string) como comprimento de byte, não contagem de caracteres. Use range ou utf8.RuneCountInString para texto visível ao usuário.
Pré-aloque slices quando o tamanho for conhecido. make([]T, 0, n) reduz as alocações em loops críticos.
Atribua o resultado de append. s = append(s, x) porque append pode retornar um novo cabeçalho.

C - Ponteiros, structs e APIs

Use receptores de ponteiro quando os métodos modificam o estado. Mantenha receptores de valor para tipos imutáveis pequenos, a menos que a consistência exija ponteiros.
Passe ponteiros para structs grandes apenas após profiling ou necessidades claras de mutação. Use valores como padrão para registros pequenos.
Verifique ponteiros nil antes de desreferenciar nas fronteiras da API. Documente se as funções aceitam nil para parâmetros opcionais.
Incorpore tipos deliberadamente, não para falsa herança. Métodos promovidos devem ser lidos como capacidades naturais do tipo externo.
Prefira campos de struct nomeados em literais. Literais posicionais quebram quando os campos são reordenados ou adicionados.

D - Pacotes, layout e ferramentas

Mantenha main enxuto; coloque a lógica em pacotes importáveis. Um módulo pode hospedar pontos de entrada cmd/ e código de biblioteca lado a lado.
Use internal/ para código que não deve vazar entre módulos. Deixe o compilador impor limites em vez de apenas comentários.
Execute go fmt ./... antes de cada commit. Formatação consistente remove debates de estilo na revisão.
Execute go test ./... e go vet ./... em CI. Erros fundamentais devem falhar rapidamente na automação.
Fixe versões de módulos em go.mod e comite go.sum. Builds reproduzíveis começam com um grafo de módulos limpo.

FAQs

Devo sempre usar ponteiros para structs?

Não - structs pequenas são mais baratas por valor.

Use ponteiros para mutação, campos opcionais ou custo de cópia comprovado.

É errado usar variáveis em nível de pacote?

Constantes e variáveis somente leitura são aceitáveis.

Estado de pacote mutável requer sincronização e prejudica a testabilidade - evite, a menos que esteja encapsulando primitivas sync por design.

Quando devo usar arrays em vez de slices?

Raramente - tamanhos fixos de rede, blocos criptográficos ou restrições incorporadas.

Use slices como padrão para código de aplicação.

Quão rigoroso deve ser o embedding?

Incorpore quando o tipo externo expõe genuinamente o comportamento incorporado (Server registra via Logger incorporado).

Use campos nomeados quando a relação for "tem um", não "se comporta como".

Por que atribuir resultados de append?

append pode realocar e retornar um cabeçalho de slice diferente.

Ignorar o retorno deixa você apontando para capacidade ou dados obsoletos.

Devo nomear todos os valores de retorno?

Retornos nomeados ajudam na documentação em funções pequenas; evite quando obscurecem a clareza.

Código fundamental deve favorecer return x, err explícito.

Como evitar bugs de variáveis de loop em goroutines?

Passe variáveis de loop como parâmetros de função.

No Go 1.22+, variáveis por iteração reduzem o risco, mas parâmetros explícitos permanecem mais claros.

O que pertence a cmd/ vs. raiz do pacote?

cmd/<app>/main.go contém executáveis; código de biblioteca vive em pacotes importáveis na raiz do módulo ou pkg/ por convenção da equipe.

Slice nil é aceitável em APIs JSON?

Slices nil geralmente codificam como null; slices vazios como [].

Escolha intencionalmente para contratos de API e documente a escolha.

Quando devo usar internal/?

Sempre que o código não puder ser importado por outros módulos - auxiliares vinculados a um produto, não um SDK público.

Preciso de construtores para todas as structs?

Apenas quando validação ou invariantes são necessários.

Prefira valores zero úteis para structs de configuração simples.

Como as melhores práticas se relacionam com golangci-lint?

Ative linters como govet, staticcheck e errcheck para impor muitos desses hábitos automaticamente em CI.

Relacionado

Fundamentos Básicos de Go - Introdução executável cobrindo esses hábitos em código
Como os Programas Go São Estruturados - Modelo mental de layout de pacote e toolchain
Variáveis, Constantes e Escopo - Regras de declaração e escopo em profundidade
Valores Zero e Inicialização - Padrões seguros e padrões make
Ponteiros e o Operador de Endereço - Quando os ponteiros valem sua complexidade

Links Relacionados Externos

Effective Go - Guia oficial para escrever Go claro e idiomático.
Go Wiki – Learn - Recursos de aprendizado curados pela comunidade.
Learn Go with Tests - Introdução ao Go focada em TDD.
Learning Go (2ª Edição, O'Reilly) - Jon Bodner na O'Reilly.
Concurrency in Go - Katherine Cox-Buday.

Versões de Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, go fix modernizers - verifique o patch na compilação), chi (última versão - verifique na compilação), gin (última versão - verifique na compilação), echo (última versão - verifique na compilação), google.golang.org/grpc (última versão - verifique na compilação), sigs.k8s.io/controller-runtime (última versão - verifique na compilação), kubebuilder (última versão - verifique na compilação), tinygo (última versão - verifique os alvos de placa na compilação), wazero (última versão - verifique na compilação) e golangci-lint (última versão - verifique o conjunto de linters na compilação).

Boas Práticas Fundamentais de Go

Buscar na documentação

Boas Práticas Fundamentais de Go